From a538644560b60d7dcbcd94aa428ffa05701f758c Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 12 Jan 2018 13:50:19 +1100
Subject: [PATCH 001/112] config: Add new Python & kconfiglib-based config
 management tool

---
 tools/kconfig_new/confgen.py         |  150 +
 tools/kconfig_new/gen_kconfig_doc.py |  127 +
 tools/kconfig_new/kconfiglib.py      | 4317 ++++++++++++++++++++++++++
 3 files changed, 4594 insertions(+)
 create mode 100755 tools/kconfig_new/confgen.py
 create mode 100644 tools/kconfig_new/gen_kconfig_doc.py
 create mode 100644 tools/kconfig_new/kconfiglib.py

diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
new file mode 100755
index 000000000..afca4176d
--- /dev/null
+++ b/tools/kconfig_new/confgen.py
@@ -0,0 +1,150 @@
+#!/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 gen_kconfig_doc
+import kconfiglib
+
+__version__ = "0.1"
+
+def main():
+    parser = argparse.ArgumentParser(description='confgen.py v%s - Config Generation Tool' % __version__, prog='conftool')
+
+    parser.add_argument('--config',
+                        help='Project configuration settings',
+                        nargs='?',
+                        default=None)
+
+    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'))
+
+    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.config is not None:
+        config.load_config(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 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 }
+
+if __name__ == '__main__':
+    main()
diff --git a/tools/kconfig_new/gen_kconfig_doc.py b/tools/kconfig_new/gen_kconfig_doc.py
new file mode 100644
index 000000000..6614c54c3
--- /dev/null
+++ b/tools/kconfig_new/gen_kconfig_doc.py
@@ -0,0 +1,127 @@
+#!/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 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 = 2
+MAX_HEADING_LEVEL = 5
+
+def write_docs(config, filename):
+    """ Note: writing .rst documentation ignores the current value
+    of any items. ie the --config option can be ignored. """
+    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 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 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('%s%s\n' % (INDENT, node.help.replace('\n', '\n%s' % 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 = choice_node.help.replace('\n', '\n%s  ' % HELP_INDENT)
+                f.write('%s  \n%s  %s\n' % (HELP_INDENT, 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'")
+
diff --git a/tools/kconfig_new/kconfiglib.py b/tools/kconfig_new/kconfiglib.py
new file mode 100644
index 000000000..527c5a55a
--- /dev/null
+++ b/tools/kconfig_new/kconfiglib.py
@@ -0,0 +1,4317 @@
+# Copyright (c) 2011-2017, Ulf Magnusson
+# Modifications (c) 2018 Espressif Systems
+# SPDX-License-Identifier: ISC
+#
+# ******* IMPORTANT **********
+#
+# This is kconfiglib 2.1.0 with some modifications to match the behaviour
+# of the ESP-IDF kconfig:
+#
+# - 'source' nows uses wordexp(3) behaviour to allow source-ing multiple
+#   files at once, and to expand environment variables directly in the source
+#   command (without them having to be set as properties in the Kconfig file)
+#
+# - Added walk_menu() function and refactored to use this internally.
+#
+# - BOOL & TRISTATE items are allowed to have blank values in .config
+#   (equivalent to n, this is backwards compatibility with old IDF conf.c)
+#
+"""
+Overview
+========
+
+Kconfiglib is a Python 2/3 library for scripting and extracting information
+from Kconfig configuration systems. It can be used for the following, among
+other things:
+
+ - Programmatically get and set symbol values
+
+   allnoconfig.py and allyesconfig.py examples are provided, automatically
+   verified to produce identical output to the standard 'make allnoconfig' and
+   'make allyesconfig'.
+
+ - Read and write .config files
+
+   The generated .config files are character-for-character identical to what
+   the C implementation would generate (except for the header comment). The
+   test suite relies on this, as it compares the generated files.
+
+ - Inspect symbols
+
+   Printing a symbol gives output which could be fed back into a Kconfig parser
+   to redefine it***. The printing function (__str__()) is implemented with
+   public APIs, meaning you can fetch just whatever information you need as
+   well.
+
+   A helpful __repr__() is implemented on all objects too, also implemented
+   with public APIs.
+
+   ***Choice symbols get their parent choice as a dependency, which shows up as
+   e.g. 'prompt "choice symbol" if <choice>' when printing the symbol. This
+   could easily be worked around if 100% reparsable output is needed.
+
+ - Inspect expressions
+
+   Expressions use a simple tuple-based format that can be processed manually
+   if needed. Expression printing and evaluation functions are provided,
+   implemented with public APIs.
+
+ - Inspect the menu tree
+
+   The underlying menu tree is exposed, including submenus created implicitly
+   from symbols depending on preceding symbols. This can be used e.g. to
+   implement menuconfig-like functionality. See the menuconfig.py example.
+
+
+Here are some other features:
+
+ - Single-file implementation
+
+   The entire library is contained in this file.
+
+ - Runs unmodified under both Python 2 and Python 3
+
+   The code mostly uses basic Python features and has no third-party
+   dependencies. The most advanced things used are probably @property and
+   __slots__.
+
+ - Robust and highly compatible with the standard Kconfig C tools
+
+   The test suite automatically compares output from Kconfiglib and the C tools
+   by diffing the generated .config files for the real kernel Kconfig and
+   defconfig files, for all ARCHes.
+
+   This currently involves comparing the output for 36 ARCHes and 498 defconfig
+   files (or over 18000 ARCH/defconfig combinations in "obsessive" test suite
+   mode). All tests are expected to pass.
+
+ - Not horribly slow despite being a pure Python implementation
+
+   The allyesconfig.py example currently runs in about 1.6 seconds on a Core i7
+   2600K (with a warm file cache), where half a second is overhead from 'make
+   scriptconfig' (see below).
+
+   For long-running jobs, PyPy gives a big performance boost. CPython is faster
+   for short-running jobs as PyPy needs some time to warm up.
+
+ - Internals that (mostly) mirror the C implementation
+
+   While being simpler to understand.
+
+
+Using Kconfiglib on the Linux kernel with the Makefile targets
+==============================================================
+
+For the Linux kernel, a handy interface is provided by the
+scripts/kconfig/Makefile patch. Apply it with either 'git am' or the 'patch'
+utility:
+
+  $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | git am
+  $ wget -qO- https://raw.githubusercontent.com/ulfalizer/Kconfiglib/master/makefile.patch | patch -p1
+
+Warning: Not passing -p1 to patch will cause the wrong file to be patched.
+
+Please tell me if the patch does not apply. It should be trivial to apply
+manually, as it's just a block of text that needs to be inserted near the other
+*conf: targets in scripts/kconfig/Makefile.
+
+If you do not wish to install Kconfiglib via pip, the Makefile patch is set up
+so that you can also just clone Kconfiglib into the kernel root:
+
+  $ git clone git://github.com/ulfalizer/Kconfiglib.git
+  $ git am Kconfiglib/makefile.patch  (or 'patch -p1 < Kconfiglib/makefile.patch')
+
+Warning: The directory name Kconfiglib/ is significant in this case, because
+it's added to PYTHONPATH by the new targets in makefile.patch.
+
+Look further down for a motivation for the Makefile patch and for instructions
+on how you can use Kconfiglib without it.
+
+The Makefile patch adds the following targets:
+
+
+make [ARCH=<arch>] iscriptconfig
+--------------------------------
+
+This target gives an interactive Python prompt where a Kconfig instance has
+been preloaded and is available in 'kconf'. To change the Python interpreter
+used, pass PYTHONCMD=<executable> to make. The default is "python".
+
+To get a feel for the API, try evaluating and printing the symbols in
+kconf.defined_syms, and explore the MenuNode menu tree starting at
+kconf.top_node by following 'next' and 'list' pointers.
+
+The item contained in a menu node is found in MenuNode.item (note that this can
+be one of the constants MENU and COMMENT), and all symbols and choices have a
+'nodes' attribute containing their menu nodes (usually only one). Printing a
+menu node will print its item, in Kconfig format.
+
+If you want to look up a symbol by name, use the kconf.syms dictionary.
+
+
+make scriptconfig SCRIPT=<script> [SCRIPT_ARG=<arg>]
+----------------------------------------------------
+
+This target runs the Python script given by the SCRIPT parameter on the
+configuration. sys.argv[1] holds the name of the top-level Kconfig file
+(currently always "Kconfig" in practice), and sys.argv[2] holds the SCRIPT_ARG
+argument, if given.
+
+See the examples/ subdirectory for example scripts.
+
+
+Using Kconfiglib without the Makefile targets
+=============================================
+
+The make targets are only needed for a trivial reason: The Kbuild makefiles
+export environment variables which are referenced inside the Kconfig files (via
+'option env="ENV_VARIABLE"').
+
+In practice, the only variables referenced (as of writing, and for many years)
+are ARCH, SRCARCH, and KERNELVERSION. To run Kconfiglib without the Makefile
+patch, do this:
+
+  $ ARCH=x86 SRCARCH=x86 KERNELVERSION=`make kernelversion` python
+  >>> import kconfiglib
+  >>> kconf = kconfiglib.Kconfig()  # filename defaults to "Kconfig"
+
+Search the top-level Makefile for "Additional ARCH settings" to see other
+possibilities for ARCH and SRCARCH. Kconfiglib will print a warning if an unset
+environment variable is referenced inside the Kconfig files.
+
+
+Gotcha
+******
+
+It's important to set $SRCARCH even if you don't care about values and only
+want to extract information from Kconfig files, because the top-level Makefile
+does this (as of writing):
+
+  source "arch/$SRCARCH/Kconfig"
+
+If $SRCARCH is not set, this expands to "arch//Kconfig", and arch/Kconfig
+happens to be an existing file, giving something that appears to work but is
+actually a truncated configuration. The available symbols will differ depending
+on the arch as well.
+
+
+Intro to symbol values
+======================
+
+Kconfiglib has the same assignment semantics as the C implementation.
+
+Any symbol can be assigned a value by the user (via Kconfig.load_config() or
+Symbol.set_value()), but this user value is only respected if the symbol is
+visible, which corresponds to it (currently) being visible in the menuconfig
+interface.
+
+Symbols without prompts are never visible (setting a user value on them is
+pointless). For symbols with prompts, the visibility of the symbol is
+determined by the condition on the prompt.
+
+Dependencies from parents and 'if'/'depends on' are propagated to properties,
+including prompts, so these two configurations are logically equivalent:
+
+(1)
+
+  menu "menu"
+  depends on A
+
+  if B
+
+  config FOO
+      tristate "foo" if D
+      default y
+      depends on C
+
+  endif
+
+  endmenu
+
+(2)
+
+  menu "menu"
+  depends on A
+
+  config FOO
+      tristate "foo" if A && B && C && D
+      default y if A && B && C
+
+  endmenu
+
+In this example, A && B && C && D (the prompt condition) needs to be non-n for
+FOO to be visible (assignable). If the value is m, the symbol can only be
+assigned the value m. The visibility sets an upper bound on the value that can
+be assigned by the user, and any higher user value will be truncated down.
+
+'default' properties are independent of the visibility, though a 'default' will
+often get the same condition as the prompt due to dependency propagation.
+'default' properties are used if the symbol is not visible or has no user
+value.
+
+Symbols with no (active) user value and no (active) 'default' default to n for
+bool/tristate symbols, and to the empty string for other symbols.
+
+'select' works similarly to symbol visibility, but sets a lower bound on the
+value of the symbol. The lower bound is determined by the value of the
+select*ing* symbol. 'select' does not respect visibility, so non-visible
+symbols can be forced to a particular (minimum) value by a select as well.
+
+For non-bool/tristate symbols, it only matters whether the visibility is n or
+non-n: m visibility acts the same as y visibility.
+
+Conditions on 'default' and 'select' work in mostly intuitive ways. If the
+condition is n, the 'default' or 'select' is disabled. If it is m, the
+'default' or 'select' value (the value of the selecting symbol) is truncated
+down to m.
+
+When writing a configuration with Kconfig.write_config(), only symbols that are
+visible, have an (active) default, or are selected will get written out (note
+that this includes all symbols that would accept user values). Kconfiglib
+matches the .config format produced by the C implementations down to the
+character. This eases testing.
+
+In Kconfiglib, the set of (currently) assignable values for a bool/tristate
+symbol appear in Symbol.assignable. For other symbol types, just check if
+sym.visibility is non-0 (non-n).
+
+
+Intro to the menu tree
+======================
+
+The menu structure, as seen in e.g. menuconfig, is represented by a tree of
+MenuNode objects. The top node of the configuration corresponds to an implicit
+top-level menu, the title of which is shown at the top in the standard
+menuconfig interface. (The title with variables expanded is available in
+Kconfig.mainmenu_text in Kconfiglib.)
+
+The top node is found in Kconfig.top_node. From there, you can visit child menu
+nodes by following the 'list' pointer, and any following menu nodes by
+following the 'next' pointer. Usually, a non-None 'list' pointer indicates a
+menu or Choice, but menu nodes for symbols can sometimes have a non-None 'list'
+pointer too due to submenus created implicitly from dependencies.
+
+MenuNode.item is either a Symbol or a Choice object, or one of the constants
+MENU and COMMENT. The prompt of the menu node (which also holds the text for
+menus and comments) can be found in MenuNode.prompt. For Symbol and Choice,
+MenuNode.help holds the help text (if any, otherwise None).
+
+Note that prompts and help texts for symbols and choices are stored in the menu
+node. This makes it possible to define a symbol in multiple locations with a
+different prompt or help text in each location.
+
+This organization mirrors the C implementation. MenuNode is called
+'struct menu' there, but I thought "menu" was a confusing name.
+
+The list of menu nodes for a Symbol or Choice can be found in the
+Symbol/Choice.nodes attribute.
+
+It is possible to give a Choice a name and define it in multiple locations,
+hence why Choice.nodes is a list. In practice, you're unlikely to ever see a
+choice defined in more than one location. I don't think I've even seen a named
+choice outside of the test suite.
+
+
+Intro to expressions
+====================
+
+Expressions can be evaluated with the expr_value() function and printed with
+the expr_str() function (these are used internally as well). Evaluating an
+expression always yields a tristate value, where n, m, and y are represented as
+0, 1, and 2, respectively.
+
+The following table should help you figure out how expressions are represented.
+A, B, C, ... are symbols (Symbol instances), NOT is the kconfiglib.NOT
+constant, etc.
+
+Expression            Representation
+----------            --------------
+A                     A
+"A"                   A (constant symbol)
+!A                    (NOT, A)
+A && B                (AND, A, B)
+A && B && C           (AND, A, (AND, B, C))
+A || B                (OR, A, B)
+A || (B && C && D)    (OR, A, (AND, B, (AND, C, D)))
+A = B                 (EQUAL, A, B)
+A != "foo"            (UNEQUAL, A, foo (constant symbol))
+A && B = C && D       (AND, A, (AND, (EQUAL, B, C), D))
+n                     Kconfig.n (constant symbol)
+m                     Kconfig.m (constant symbol)
+y                     Kconfig.y (constant symbol)
+"y"                   Kconfig.y (constant symbol)
+
+Strings like "foo" in 'default "foo"' or 'depends on SYM = "foo"' are
+represented as constant symbols, so the only values that appear in expressions
+are symbols***. This mirrors the C implementation.
+
+***For choice symbols, the parent Choice will appear in expressions as well,
+but it's usually invisible as the value interfaces of Symbol and Choice are
+identical. This mirrors the C implementation and makes different choice modes
+"just work".
+
+Manual evaluation examples:
+
+  - The value of A && B is min(A.tri_value, B.tri_value)
+
+  - The value of A || B is max(A.tri_value, B.tri_value)
+
+  - The value of !A is 2 - A.tri_value
+
+  - The value of A = B is 2 (y) if A.str_value == B.str_value, and 0 (n)
+    otherwise. Note that str_value is used here instead of tri_value.
+
+    For constant (as well as undefined) symbols, str_value matches the name of
+    the symbol. This mirrors the C implementation and explains why
+    'depends on SYM = "foo"' above works as expected.
+
+n/m/y are automatically converted to the corresponding constant symbols
+"n"/"m"/"y" (Kconfig.n/m/y) during parsing.
+
+Kconfig.const_syms is a dictionary like Kconfig.syms but for constant symbols.
+
+If a condition is missing (e.g., <cond> when the 'if <cond>' is removed from
+'default A if <cond>'), it is actually Kconfig.y. The standard __str__()
+functions just avoid printing 'if y' conditions to give cleaner output.
+
+
+Feedback
+========
+
+Send bug reports, suggestions, and questions to ulfalizer a.t Google's email
+service, or open a ticket on the GitHub page.
+"""
+import errno
+import os
+import platform
+import re
+import sys
+
+# File layout:
+#
+# Public classes
+# Public functions
+# Internal functions
+# Public global constants
+# Internal global constants
+
+# Line length: 79 columns
+
+#
+# Public classes
+#
+
+class Kconfig(object):
+    """
+    Represents a Kconfig configuration, e.g. for x86 or ARM. This is the set of
+    symbols, choices, and menu nodes appearing in the configuration. Creating
+    any number of Kconfig objects (including for different architectures) is
+    safe. Kconfiglib doesn't keep any global state.
+
+    The following attributes are available. They should be treated as
+    read-only, and some are implemented through @property magic.
+
+    syms:
+      A dictionary with all symbols in the configuration, indexed by name. Also
+      includes all symbols that are referenced in expressions but never
+      defined, except for constant (quoted) symbols.
+
+    const_syms:
+      A dictionary like 'syms' for constant (quoted) symbols.
+
+    named_choices:
+      A dictionary like 'syms' for named choices (choice FOO). This is for
+      completeness. I've never seen a named choice outside of the test suite.
+
+    defined_syms:
+      A list with all defined symbols, in the same order as they appear in the
+      Kconfig files. Provided as a convenience.
+
+    n/m/y:
+      The predefined constant symbols n/m/y. Also available in const_syms.
+
+    modules:
+      The Symbol instance for the modules symbol. Currently hardcoded to
+      MODULES, which is backwards compatible. Kconfiglib will warn if
+      'option modules' is set on some other symbol. Tell me if you need proper
+      'option modules' support.
+
+      'modules' is never None. If the MODULES symbol is not explicitly defined,
+      its tri_value will be 0 (n), as expected.
+
+      A simple way to enable modules is to do 'kconf.modules.set_value(2)'
+      (provided the MODULES symbol is defined and visible). Modules are
+      disabled by default in the kernel Kconfig files as of writing, though
+      nearly all defconfig files enable them (with 'CONFIG_MODULES=y').
+
+    defconfig_list:
+      The Symbol instance for the 'option defconfig_list' symbol, or None if no
+      defconfig_list symbol exists. The defconfig filename derived from this
+      symbol can be found in Kconfig.defconfig_filename.
+
+    defconfig_filename:
+      The filename given by the defconfig_list symbol. This is taken from the
+      first 'default' with a satisfied condition where the specified file
+      exists (can be opened for reading). If a defconfig file foo/defconfig is
+      not found and $srctree was set when the Kconfig was created,
+      $srctree/foo/defconfig is looked up as well.
+
+      References to Kconfig symbols ("$FOO") in the 'default' properties of the
+      defconfig_filename symbol are are expanded before the file is looked up.
+
+      'defconfig_filename' is None if either no defconfig_list symbol exists,
+      or if the defconfig_list symbol has no 'default' with a satisfied
+      condition that specifies a file that exists.
+
+      Gotcha: scripts/kconfig/Makefile might pass --defconfig=<defconfig> to
+      scripts/kconfig/conf when running e.g. 'make defconfig'. This option
+      overrides the defconfig_list symbol, meaning defconfig_filename might not
+      always match what 'make defconfig' would use.
+
+    top_node:
+      The menu node (see the MenuNode class) of the implicit top-level menu.
+      Acts as the root of the menu tree.
+
+    mainmenu_text:
+      The prompt (title) of the top_node menu, with Kconfig variable references
+      ("$FOO") expanded. Defaults to "Linux Kernel Configuration" (like in the
+      C tools). Can be changed with the 'mainmenu' statement (see
+      kconfig-language.txt).
+
+    srctree:
+      The value of the $srctree environment variable when the configuration was
+      loaded, or None if $srctree wasn't set. Kconfig and .config files are
+      looked up relative to $srctree if they are not found in the base path
+      (unless absolute paths are used). This is used to support out-of-tree
+      builds. The C tools use this environment variable in the same way.
+
+      Changing $srctree after creating the Kconfig instance has no effect. Only
+      the value when the configuration is loaded matters. This avoids surprises
+      if multiple configurations are loaded with different values for $srctree.
+
+    config_prefix:
+      The value of the $CONFIG_ environment variable when the configuration was
+      loaded. This is the prefix used (and expected) in .config files. Defaults
+      to "CONFIG_". Used in the same way in the C tools.
+
+      Like for srctree, only the value of $CONFIG_ when the configuration is
+      loaded matters.
+    """
+    __slots__ = (
+        "_choices",
+        "_print_undef_assign",
+        "_print_warnings",
+        "_set_re_match",
+        "_unset_re_match",
+        "_warn_no_prompt",
+        "config_prefix",
+        "const_syms",
+        "defconfig_list",
+        "defined_syms",
+        "m",
+        "modules",
+        "n",
+        "named_choices",
+        "srctree",
+        "syms",
+        "top_node",
+        "y",
+
+        # Parsing-related
+        "_parsing_kconfigs",
+        "_reuse_line",
+        "_file",
+        "_filename",
+        "_linenr",
+        "_filestack",
+        "_line",
+        "_tokens",
+        "_tokens_i",
+        "_has_tokens",
+    )
+
+    #
+    # Public interface
+    #
+
+    def __init__(self, filename="Kconfig", warn=True):
+        """
+        Creates a new Kconfig object by parsing Kconfig files. Raises
+        KconfigSyntaxError on syntax errors. Note that Kconfig files are not
+        the same as .config files (which store configuration symbol values).
+
+        filename (default: "Kconfig"):
+          The base Kconfig file. For the Linux kernel, you'll want "Kconfig"
+          from the top-level directory, as environment variables will make sure
+          the right Kconfig is included from there (arch/$SRCARCH/Kconfig as of
+          writing).
+
+          If you are using Kconfiglib via 'make scriptconfig', the filename of
+          the base base Kconfig file will be in sys.argv[1]. It's currently
+          always "Kconfig" in practice.
+
+          The $srctree environment variable is used to look up Kconfig files if
+          set. See the class documentation.
+
+        warn (default: True):
+          True if warnings related to this configuration should be printed to
+          stderr. This can be changed later with
+          Kconfig.enable/disable_warnings(). It is provided as a constructor
+          argument since warnings might be generated during parsing.
+        """
+        self.srctree = os.environ.get("srctree")
+
+        self.config_prefix = os.environ.get("CONFIG_")
+        if self.config_prefix is None:
+            self.config_prefix = "CONFIG_"
+
+        # Regular expressions for parsing .config files, with the get() method
+        # assigned directly as a small optimization (microscopic in this case,
+        # but it's consistent with the other regexes)
+        self._set_re_match = re.compile(r"{}(\w+)=(.*)"
+                                        .format(self.config_prefix)).match
+        self._unset_re_match = re.compile(r"# {}(\w+) is not set"
+                                          .format(self.config_prefix)).match
+
+        self._print_warnings = warn
+        self._print_undef_assign = False
+
+        self.syms = {}
+        self.const_syms = {}
+        self.defined_syms = []
+        self.named_choices = {}
+        # Used for quickly invalidating all choices
+        self._choices = []
+
+        for nmy in "n", "m", "y":
+            sym = Symbol()
+            sym.kconfig = self
+            sym.name = nmy
+            sym.is_constant = True
+            sym.orig_type = TRISTATE
+            sym._cached_tri_val = STR_TO_TRI[nmy]
+
+            self.const_syms[nmy] = sym
+
+        self.n = self.const_syms["n"]
+        self.m = self.const_syms["m"]
+        self.y = self.const_syms["y"]
+
+        # Make n/m/y well-formed symbols
+        for nmy in "n", "m", "y":
+            sym = self.const_syms[nmy]
+            sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
+
+        # This is used to determine whether previously unseen symbols should be
+        # registered. They shouldn't be if we parse expressions after parsing,
+        # as part of Kconfig.eval_string().
+        self._parsing_kconfigs = True
+
+        self.modules = self._lookup_sym("MODULES")
+        self.defconfig_list = None
+
+        # The only predefined symbol besides n/m/y. DEFCONFIG_LIST uses this as
+        # of writing.
+        uname_sym = self._lookup_const_sym("UNAME_RELEASE")
+        uname_sym.orig_type = STRING
+        # env_var doubles as the SYMBOL_AUTO flag from the C implementation, so
+        # just set it to something. The naming breaks a bit here.
+        uname_sym.env_var = "<uname release>"
+        uname_sym.defaults.append(
+            (self._lookup_const_sym(platform.uname()[2]), self.y))
+        self.syms["UNAME_RELEASE"] = uname_sym
+
+        self.top_node = MenuNode()
+        self.top_node.kconfig = self
+        self.top_node.item = MENU
+        self.top_node.visibility = self.y
+        self.top_node.prompt = ("Linux Kernel Configuration", self.y)
+        self.top_node.parent = None
+        self.top_node.dep = self.y
+        self.top_node.filename = filename
+        self.top_node.linenr = 1
+
+        # Parse the Kconfig files
+
+        # These implement a single line of "unget" for the parser
+        self._reuse_line = False
+        self._has_tokens = False
+
+        # Keeps track of the location in the parent Kconfig files. Kconfig
+        # files usually source other Kconfig files.
+        self._filestack = []
+
+        # The current parsing location
+        self._filename = filename
+        self._linenr = 0
+
+        self._file = self._open(filename)
+
+        self._parse_block(None,           # end_token
+                          self.top_node,  # parent
+                          self.y,         # visible_if_deps
+                          self.top_node)  # prev_node
+        self.top_node.list = self.top_node.next
+        self.top_node.next = None
+
+        self._parsing_kconfigs = False
+
+        # Do various post-processing of the menu tree
+        _finalize_tree(self.top_node)
+
+        # Build Symbol._dependents for all symbols
+        self._build_dep()
+
+        self._warn_no_prompt = True
+
+    @property
+    def mainmenu_text(self):
+        """
+        See the class documentation.
+        """
+        return self._expand_syms(self.top_node.prompt[0])
+
+    @property
+    def defconfig_filename(self):
+        """
+        See the class documentation.
+        """
+        if not self.defconfig_list:
+            return None
+
+        for filename, cond in self.defconfig_list.defaults:
+            if expr_value(cond):
+                try:
+                    with self._open(self._expand_syms(filename.str_value)) as f:
+                        return f.name
+                except IOError:
+                    continue
+
+        return None
+
+    def load_config(self, filename, replace=True):
+        """
+        Loads symbol values from a file in the .config format. Equivalent to
+        calling Symbol.set_value() to set each of the values.
+
+        "# CONFIG_FOO is not set" within a .config file sets the user value of
+        FOO to n. The C tools work the same way.
+
+        filename:
+          The file to load. Respects $srctree if set (see the class
+          documentation).
+
+        replace (default: True):
+          True if all existing user values should be cleared before loading the
+          .config.
+        """
+        # Disable the warning about assigning to symbols without prompts. This
+        # is normal and expected within a .config file.
+        self._warn_no_prompt = False
+
+        # This stub only exists to make sure _warn_no_prompt gets reenabled
+        try:
+            self._load_config(filename, replace)
+        finally:
+            self._warn_no_prompt = True
+
+    def _load_config(self, filename, replace):
+        with self._open(filename) as f:
+            if replace:
+                # If we're replacing the configuration, keep track of which
+                # symbols and choices got set so that we can unset the rest
+                # later. This avoids invalidating everything and is faster.
+                # Another benefit is that invalidation must be rock solid for
+                # it to work, making it a good test.
+
+                for sym in self.defined_syms:
+                    sym._was_set = False
+
+                for choice in self._choices:
+                    choice._was_set = False
+
+            # Small optimizations
+            set_re_match = self._set_re_match
+            unset_re_match = self._unset_re_match
+            syms = self.syms
+
+            for linenr, line in enumerate(f, 1):
+                # The C tools ignore trailing whitespace
+                line = line.rstrip()
+
+                set_match = set_re_match(line)
+                if set_match:
+                    name, val = set_match.groups()
+                    if name not in syms:
+                        self._warn_undef_assign_load(name, val, filename,
+                                                     linenr)
+                        continue
+
+                    sym = syms[name]
+                    if not sym.nodes:
+                        self._warn_undef_assign_load(name, val, filename,
+                                                     linenr)
+                        continue
+
+                    if sym.orig_type in (BOOL, TRISTATE):
+                        # The C implementation only checks the first character
+                        # to the right of '=', for whatever reason
+                        if not ((sym.orig_type == BOOL and
+                                 val.startswith(("n", "y"))) or \
+                                (sym.orig_type == TRISTATE and
+                                 val.startswith(("n", "m", "y")))):
+                            if val != "":  # workaround for old IDF conf behaviour
+                                self._warn("'{}' is not a valid value for the {} "
+                                           "symbol {}. Assignment ignored."
+                                           .format(val, TYPE_TO_STR[sym.orig_type],
+                                                   sym.name))
+                            continue
+
+                        # We represent tristate values as 0, 1, 2
+                        val = STR_TO_TRI[val[0]]
+
+                        if sym.choice and val:
+                            # During .config loading, we infer the mode of the
+                            # choice from the kind of values that are assigned
+                            # to the choice symbols
+
+                            prev_mode = sym.choice.user_value
+                            if prev_mode is not None and prev_mode != val:
+                                self._warn("both m and y assigned to symbols "
+                                           "within the same choice",
+                                           filename, linenr)
+
+                            # Set the choice's mode
+                            sym.choice.set_value(val)
+
+                    elif sym.orig_type == STRING:
+                        string_match = _conf_string_re_match(val)
+                        if not string_match:
+                            self._warn("Malformed string literal in "
+                                       "assignment to {}. Assignment ignored."
+                                       .format(sym.name),
+                                       filename, linenr)
+                            continue
+
+                        val = unescape(string_match.group(1))
+
+                else:
+                    unset_match = unset_re_match(line)
+                    if not unset_match:
+                        continue
+
+                    name = unset_match.group(1)
+                    if name not in syms:
+                        self._warn_undef_assign_load(name, "n", filename,
+                                                     linenr)
+                        continue
+
+                    sym = syms[name]
+                    if sym.orig_type not in (BOOL, TRISTATE):
+                        continue
+
+                    val = 0
+
+                # Done parsing the assignment. Set the value.
+
+                if sym._was_set:
+                    # Use strings for tristate values in the warning
+                    if sym.orig_type in (BOOL, TRISTATE):
+                        display_val = TRI_TO_STR[val]
+                        display_user_val = TRI_TO_STR[sym.user_value]
+                    else:
+                        display_val = val
+                        display_user_val = sym.user_value
+
+                    self._warn('{} set more than once. Old value: "{}", new '
+                               'value: "{}".'
+                               .format(name, display_user_val, display_val),
+                               filename, linenr)
+
+                sym.set_value(val)
+
+        if replace:
+            # If we're replacing the configuration, unset the symbols that
+            # didn't get set
+
+            for sym in self.defined_syms:
+                if not sym._was_set:
+                    sym.unset_value()
+
+            for choice in self._choices:
+                if not choice._was_set:
+                    choice.unset_value()
+
+    def write_autoconf(self, filename,
+                       header="/* Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib) */\n"):
+        r"""
+        Writes out symbol values as a C header file, matching the format used
+        by include/generated/autoconf.h in the kernel (though possibly with a
+        different ordering of the #defines, as the order in the C
+        implementation depends on the hash table implementation as of writing).
+
+        filename:
+          Self-explanatory.
+
+        header (default: "/* Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib) */\n"):
+          Text that will be inserted verbatim at the beginning of the file. You
+          would usually want it enclosed in '/* */' to make it a C comment,
+          and include a final terminating newline.
+        """
+        with open(filename, "w") as f:
+
+            # Small optimizations
+            write = f.write
+            config_prefix = self.config_prefix
+
+            write(header)
+
+            def write_node(node):
+                sym = node.item
+                if not isinstance(sym, Symbol):
+                    return
+
+                # Note: _write_to_conf is determined when the value is
+                # calculated. This is a hidden function call due to
+                # property magic.
+                val = sym.str_value
+                if sym._write_to_conf:
+                    orig_type = sym.orig_type
+                    if orig_type in (BOOL, TRISTATE):
+                        if val != "n":
+                            write("#define {}{}{} 1\n"
+                                  .format(config_prefix, sym.name,
+                                          "_MODULE" if val == "m" else ""))
+
+                    elif orig_type == STRING:
+                        write('#define {}{} "{}"\n'
+                              .format(config_prefix, sym.name,
+                                          escape(val)))
+
+                    elif orig_type in (INT, HEX):
+                        if orig_type == HEX and \
+                           not val.startswith(("0x", "0X")):
+                            val = "0x" + val
+
+                        write("#define {}{} {}\n"
+                              .format(self.config_prefix, sym.name, val))
+
+                    else:
+                        _internal_error("Internal error while creating C "
+                                        'header: unknown type "{}".'
+                                        .format(sym.orig_type))
+
+            self.walk_menu(write_node)
+
+    def write_config(self, filename,
+                     header="# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"):
+        r"""
+        Writes out symbol values in the .config format.
+
+        filename:
+          Self-explanatory.
+
+        header (default: "# Generated by Kconfiglib (https://github.com/ulfalizer/Kconfiglib)\n"):
+          Text that will be inserted verbatim at the beginning of the file. You
+          would usually want each line to start with '#' to make it a comment,
+          and include a final terminating newline.
+        """
+        with open(filename, "w") as f:
+            # Small optimization
+            write = f.write
+
+            write(header)
+
+            def write_node(node):
+                item = node.item
+                if isinstance(item, Symbol):
+                    config_string = item.config_string
+                    if config_string:
+                        write(config_string)
+
+                elif expr_value(node.dep) and \
+                     ((item == MENU and expr_value(node.visibility)) or
+                       item == COMMENT):
+
+                    write("\n#\n# {}\n#\n".format(node.prompt[0]))
+            self.walk_menu(write_node, True)
+
+    def walk_menu(self, callback, skip_duplicates=False):
+        """
+        Walk the entire menu in order, calling callback(node)
+        for each menu node.
+
+        Used to implement write_config() & write_autoconf(), but can be
+        used to implement different types of custom processing as well.
+
+        callback:
+        Function which is called once for each node in the config tree.
+        Takes only one argument, the node.
+
+        skip_duplicates (default: False)
+        If set to True, for each item in the menu the callback will
+        only be called the first time it is encountered in the menu.
+        """
+        node = self.top_node.list
+        if not node:
+            return  # Empty configuration
+
+        seen_items = set()
+
+        while True:
+            if not (skip_duplicates and node.item in seen_items):
+                callback(node)
+                seen_items.add(node.item)
+            if node.list:
+                node = node.list
+            elif node.next:
+                node = node.next
+            else:
+                while node.parent:
+                    node = node.parent
+                    if node.next:
+                        node = node.next
+                        break
+                else:
+                    return
+
+    def eval_string(self, s):
+        """
+        Returns the tristate value of the expression 's', represented as 0, 1,
+        and 2 for n, m, and y, respectively. Raises KconfigSyntaxError if
+        syntax errors are detected in 's'. Warns if undefined symbols are
+        referenced.
+
+        As an example, if FOO and BAR are tristate symbols at least one of
+        which has the value y, then config.eval_string("y && (FOO || BAR)")
+        returns 2 (y).
+
+        To get the string value of non-bool/tristate symbols, use
+        Symbol.str_value. eval_string() always returns a tristate value, and
+        all non-bool/tristate symbols have the tristate value 0 (n).
+
+        The expression parsing is consistent with how parsing works for
+        conditional ('if ...') expressions in the configuration, and matches
+        the C implementation. m is rewritten to 'm && MODULES', so
+        eval_string("m") will return 0 (n) unless modules are enabled.
+        """
+        # The parser is optimized to be fast when parsing Kconfig files (where
+        # an expression can never appear at the beginning of a line). We have
+        # to monkey-patch things a bit here to reuse it.
+
+        self._filename = None
+
+        self._line = "if " + s
+        self._tokenize()
+        # Remove the "if " to avoid giving confusing error messages
+        self._line = s
+        # Remove the _T_IF token
+        del self._tokens[0]
+
+        return expr_value(self._parse_expr(True))  # transform_m
+
+    def unset_values(self):
+        """
+        Resets the user values of all symbols, as if Kconfig.load_config() or
+        Symbol.set_value() had never been called.
+        """
+        self._warn_no_prompt = False
+        try:
+            # set_value() already rejects undefined symbols, and they don't
+            # need to be invalidated (because their value never changes), so we
+            # can just iterate over defined symbols
+            for sym in self.defined_syms:
+                sym.unset_value()
+
+            for choice in self._choices:
+                choice.unset_value()
+        finally:
+            self._warn_no_prompt = True
+
+    def enable_warnings(self):
+        """
+        See Kconfig.__init__().
+        """
+        self._print_warnings = True
+
+    def disable_warnings(self):
+        """
+        See Kconfig.__init__().
+        """
+        self._print_warnings = False
+
+    def enable_undef_warnings(self):
+        """
+        Enables warnings for assignments to undefined symbols. Printed to
+        stderr. Disabled by default since they tend to be spammy for Kernel
+        configurations (and mostly suggests cleanups).
+        """
+        self._print_undef_assign = True
+
+    def disable_undef_warnings(self):
+        """
+        See enable_undef_assign().
+        """
+        self._print_undef_assign = False
+
+    def __repr__(self):
+        """
+        Returns a string with information about the Kconfig object when it is
+        evaluated on e.g. the interactive Python prompt.
+        """
+        return "<{}>".format(", ".join((
+            "configuration with {} symbols".format(len(self.syms)),
+            'main menu prompt "{}"'.format(self.mainmenu_text),
+            "srctree not set" if self.srctree is None else
+                'srctree "{}"'.format(self.srctree),
+            'config symbol prefix "{}"'.format(self.config_prefix),
+            "warnings " + ("enabled" if self._print_warnings else "disabled"),
+            "undef. symbol assignment warnings " +
+                ("enabled" if self._print_undef_assign else "disabled"),
+        )))
+
+    #
+    # Private methods
+    #
+
+
+    #
+    # File reading
+    #
+
+    def _open(self, filename):
+        """
+        First tries to open 'filename', then '$srctree/filename' if $srctree
+        was set when the configuration was loaded.
+        """
+        try:
+            return open(filename)
+        except IOError as e:
+            if not os.path.isabs(filename) and self.srctree is not None:
+                filename = os.path.join(self.srctree, filename)
+                try:
+                    return open(filename)
+                except IOError as e2:
+                    # This is needed for Python 3, because e2 is deleted after
+                    # the try block:
+                    #
+                    # https://docs.python.org/3/reference/compound_stmts.html#the-try-statement
+                    e = e2
+
+            raise IOError(
+                "Could not open '{}' ({}: {}). Perhaps the $srctree "
+                "environment variable (which was {}) is set incorrectly. Note "
+                "that the current value of $srctree is saved when the Kconfig "
+                "instance is created (for consistency and to cleanly "
+                "separate instances)."
+                .format(filename, errno.errorcode[e.errno], e.strerror,
+                        "unset" if self.srctree is None else
+                        '"{}"'.format(self.srctree)))
+
+    def _enter_file(self, filename):
+        """
+        Jumps to the beginning of a sourced Kconfig file, saving the previous
+        position and file object.
+        """
+        self._filestack.append((self._file, self._filename, self._linenr))
+        try:
+            self._file = self._open(filename)
+        except IOError as e:
+            # Extend the error message a bit in this case
+            raise IOError(
+                "{}:{}: {} Also note that e.g. $FOO in a 'source' "
+                "statement does not refer to the environment "
+                "variable FOO, but rather to the Kconfig Symbol FOO "
+                "(which would commonly have 'option env=\"FOO\"' in "
+                "its definition)."
+                .format(self._filename, self._linenr, e.message))
+
+        self._filename = filename
+        self._linenr = 0
+
+    def _leave_file(self):
+        """
+        Returns from a Kconfig file to the file that sourced it.
+        """
+        self._file.close()
+        self._file, self._filename, self._linenr = self._filestack.pop()
+
+    def _next_line(self):
+        """
+        Fetches and tokenizes the next line from the current Kconfig file.
+        Returns False at EOF and True otherwise.
+        """
+        # This provides a single line of "unget" if _reuse_line is set to True
+        if not self._reuse_line:
+            self._line = self._file.readline()
+            self._linenr += 1
+
+        self._reuse_line = False
+
+        # Handle line joining
+        while self._line.endswith("\\\n"):
+            self._line = self._line[:-2] + self._file.readline()
+            self._linenr += 1
+
+        if not self._line:
+            return False
+
+        self._tokenize()
+        return True
+
+    def _next_help_line(self):
+        """
+        Used for help texts, where lines are not tokenized and no line joining
+        is done.
+        """
+        self._line = self._file.readline()
+        self._linenr += 1
+        return self._line
+
+
+    #
+    # Tokenization
+    #
+
+    def _lookup_sym(self, name):
+        """
+        Fetches the symbol 'name' from the symbol table, creating and
+        registering it if it does not exist. If '_parsing_kconfigs' is False,
+        it means we're in eval_string(), and new symbols won't be registered.
+        """
+        if name in self.syms:
+            return self.syms[name]
+
+        sym = Symbol()
+        sym.kconfig = self
+        sym.name = name
+        sym.is_constant = False
+        sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
+
+        if self._parsing_kconfigs:
+            self.syms[name] = sym
+        else:
+            self._warn("no symbol {} in configuration".format(name))
+
+        return sym
+
+    def _lookup_const_sym(self, name):
+        """
+        Like _lookup_sym(), for constant (quoted) symbols
+        """
+        if name in self.const_syms:
+            return self.const_syms[name]
+
+        sym = Symbol()
+        sym.kconfig = self
+        sym.name = name
+        sym.is_constant = True
+        sym.rev_dep = sym.weak_rev_dep = sym.direct_dep = self.n
+
+        if self._parsing_kconfigs:
+            self.const_syms[name] = sym
+
+        return sym
+
+    def _tokenize(self):
+        """
+        Parses Kconfig._line, putting the tokens in Kconfig._tokens. Registers
+        any new symbols encountered with _lookup(_const)_sym().
+
+        Tries to be reasonably speedy by processing chunks of text via regexes
+        and string operations where possible. This is the biggest hotspot
+        during parsing.
+        """
+        s = self._line
+
+        # Tricky implementation detail: While parsing a token, 'token' refers
+        # to the previous token. See _STRING_LEX for why this is needed.
+
+        # See comment at _initial_token_re_match definition
+        initial_token_match = _initial_token_re_match(s)
+        if not initial_token_match:
+            self._tokens = (None,)
+            self._tokens_i = -1
+            return
+
+        keyword = _get_keyword(initial_token_match.group(1))
+
+        if keyword == _T_HELP:
+            # Avoid junk after "help", e.g. "---", being registered as a
+            # symbol
+            self._tokens = (_T_HELP, None)
+            self._tokens_i = -1
+            return
+
+        if keyword is None:
+            self._parse_error("expected keyword as first token")
+
+        token = keyword
+        self._tokens = [keyword]
+        # The current index in the string being tokenized
+        i = initial_token_match.end()
+
+        # Main tokenization loop (for tokens past the first one)
+        while i < len(s):
+            # Test for an identifier/keyword first. This is the most common
+            # case.
+            id_keyword_match = _id_keyword_re_match(s, i)
+            if id_keyword_match:
+                # We have an identifier or keyword
+
+                # Jump past it
+                i = id_keyword_match.end()
+
+                # Check what it is. lookup_sym() will take care of allocating
+                # new symbols for us the first time we see them. Note that
+                # 'token' still refers to the previous token.
+
+                name = id_keyword_match.group(1)
+                keyword = _get_keyword(name)
+                if keyword is not None:
+                    # It's a keyword
+                    token = keyword
+
+                elif token not in _STRING_LEX:
+                    # It's a non-const symbol...
+                    if name in ("n", "m", "y"):
+                        # ...except we translate n, m, and y into the
+                        # corresponding constant symbols, like the C
+                        # implementation
+                        token = self.const_syms[name]
+                    else:
+                        token = self._lookup_sym(name)
+
+                else:
+                    # It's a case of missing quotes. For example, the
+                    # following is accepted:
+                    #
+                    #   menu unquoted_title
+                    #
+                    #   config A
+                    #       tristate unquoted_prompt
+                    #
+                    #   endmenu
+                    token = name
+
+            else:
+                # Not keyword/non-const symbol
+
+                # Note: _id_keyword_match and _initial_token_match strip
+                # trailing whitespace, making it safe to assume s[i] is the
+                # start of a token here. We manually strip trailing whitespace
+                # below as well.
+                #
+                # An old version stripped whitespace in this spot instead, but
+                # that leads to some redundancy and would cause
+                # _id_keyword_match to be tried against just "\n" fairly often
+                # (because file.readlines() keeps newlines).
+
+                c = s[i]
+                i += 1
+
+                if c in "\"'":
+                    # String literal/constant symbol
+                    if "\\" not in s:
+                        # Fast path: If the line contains no backslashes, we
+                        # can just find the matching quote.
+
+                        end = s.find(c, i)
+                        if end == -1:
+                            self._parse_error("unterminated string")
+
+                        val = s[i:end]
+                        i = end + 1
+                    else:
+                        # Slow path for lines with backslashes (very rare,
+                        # performance irrelevant)
+
+                        quote = c
+                        val = ""
+
+                        while 1:
+                            if i >= len(s):
+                                self._parse_error("unterminated string")
+
+                            c = s[i]
+                            if c == quote:
+                                break
+
+                            if c == "\\":
+                                if i + 1 >= len(s):
+                                    self._parse_error("unterminated string")
+
+                                val += s[i + 1]
+                                i += 2
+                            else:
+                                val += c
+                                i += 1
+
+                        i += 1
+
+                    # This is the only place where we don't survive with a
+                    # single token of lookback: 'option env="FOO"' does not
+                    # refer to a constant symbol named "FOO".
+                    token = val \
+                            if token in _STRING_LEX or \
+                                self._tokens[0] == _T_OPTION else \
+                            self._lookup_const_sym(val)
+
+                elif c == "&":
+                    # Invalid characters are ignored (backwards-compatible)
+                    if i >= len(s) or s[i] != "&":
+                        continue
+
+                    token = _T_AND
+                    i += 1
+
+                elif c == "|":
+                    # Invalid characters are ignored (backwards-compatible)
+                    if i >= len(s) or s[i] != "|":
+                        continue
+
+                    token = _T_OR
+                    i += 1
+
+                elif c == "!":
+                    if i < len(s) and s[i] == "=":
+                        token = _T_UNEQUAL
+                        i += 1
+                    else:
+                        token = _T_NOT
+
+                elif c == "=":
+                    token = _T_EQUAL
+
+                elif c == "(":
+                    token = _T_OPEN_PAREN
+
+                elif c == ")":
+                    token = _T_CLOSE_PAREN
+
+                elif c == "#":
+                    break
+
+                # Very rare
+                elif c == "<":
+                    if i < len(s) and s[i] == "=":
+                        token = _T_LESS_EQUAL
+                        i += 1
+                    else:
+                        token = _T_LESS
+
+                # Very rare
+                elif c == ">":
+                    if i < len(s) and s[i] == "=":
+                        token = _T_GREATER_EQUAL
+                        i += 1
+                    else:
+                        token = _T_GREATER
+
+                else:
+                    # Invalid characters are ignored (backwards-compatible)
+                    continue
+
+                # Skip trailing whitespace
+                while i < len(s) and s[i].isspace():
+                    i += 1
+
+            self._tokens.append(token)
+
+        # None-terminating token streams makes the token fetching functions
+        # simpler/faster
+        self._tokens.append(None)
+        self._tokens_i = -1
+
+    def _next_token(self):
+        self._tokens_i += 1
+        return self._tokens[self._tokens_i]
+
+    def _peek_token(self):
+        return self._tokens[self._tokens_i + 1]
+
+    def _check_token(self, token):
+        """
+        If the next token is 'token', removes it and returns True.
+        """
+        if self._tokens[self._tokens_i + 1] == token:
+            self._tokens_i += 1
+            return True
+        return False
+
+
+    #
+    # Parsing
+    #
+
+    def _make_and(self, e1, e2):
+        """
+        Constructs an AND (&&) expression. Performs trivial simplification.
+        """
+        if e1 is self.y:
+            return e2
+
+        if e2 is self.y:
+            return e1
+
+        if e1 is self.n or e2 is self.n:
+            return self.n
+
+        return (AND, e1, e2)
+
+    def _make_or(self, e1, e2):
+        """
+        Constructs an OR (||) expression. Performs trivial simplification.
+        """
+        if e1 is self.n:
+            return e2
+
+        if e2 is self.n:
+            return e1
+
+        if e1 is self.y or e2 is self.y:
+            return self.y
+
+        return (OR, e1, e2)
+
+    def _parse_block(self, end_token, parent, visible_if_deps, prev_node):
+        """
+        Parses a block, which is the contents of either a file or an if, menu,
+        or choice statement.
+
+        end_token:
+          The token that ends the block, e.g. _T_ENDIF ("endif") for ifs. None
+          for files.
+
+        parent:
+          The parent menu node, corresponding to e.g. a menu or Choice. Can
+          also be a Symbol, due to automatic submenu creation from
+          dependencies.
+
+        visible_if_deps:
+          'visible if' dependencies from enclosing menus. Propagated to Symbol
+          and Choice prompts.
+
+        prev_node:
+          The previous menu node. New nodes will be added after this one (by
+          modifying their 'next' pointer).
+
+          prev_node is reused to parse a list of child menu nodes (for a menu
+          or Choice): After parsing the children, the 'next' pointer is
+          assigned to the 'list' pointer to "tilt up" the children above the
+          node.
+
+
+        Returns the final menu node in the block (or prev_node if the block is
+        empty). This allows chaining.
+        """
+        # We might already have tokens from parsing a line to check if it's a
+        # property and discovering it isn't. self._has_tokens functions as a
+        # kind of "unget".
+        while self._has_tokens or self._next_line():
+            self._has_tokens = False
+
+            t0 = self._next_token()
+            if t0 is None:
+                continue
+
+            if t0 in (_T_CONFIG, _T_MENUCONFIG):
+                # The tokenizer allocates Symbol objects for us
+                sym = self._next_token()
+
+                node = MenuNode()
+                node.kconfig = self
+                node.item = sym
+                node.help = node.list = None
+                node.parent = parent
+                node.filename = self._filename
+                node.linenr = self._linenr
+                node.is_menuconfig = (t0 == _T_MENUCONFIG)
+
+                self._parse_properties(node, visible_if_deps)
+
+                sym.nodes.append(node)
+                self.defined_syms.append(sym)
+
+                # Tricky Python semantics: This assign prev_node.next before
+                # prev_node
+                prev_node.next = prev_node = node
+
+            elif t0 == _T_SOURCE:
+                values = _wordexp_expand(self._next_token())
+                for sourced_file in values:
+                    self._enter_file(sourced_file)
+                    prev_node = self._parse_block(None,            # end_token
+                                                  parent,
+                                                  visible_if_deps,
+                                                  prev_node)
+                    self._leave_file()
+
+            elif t0 == end_token:
+                # We have reached the end of the block. Terminate the final
+                # node and return it.
+                prev_node.next = None
+                return prev_node
+
+            elif t0 == _T_IF:
+                node = MenuNode()
+                node.item = node.prompt = None
+                node.parent = parent
+                node.filename = self._filename
+                node.linenr = self._linenr
+
+                # See similar code in _parse_properties()
+                if isinstance(parent.item, Choice):
+                    parent_dep = parent.item
+                else:
+                    parent_dep = parent.dep
+
+                node.dep = self._make_and(parent_dep, self._parse_expr(True))
+
+                self._parse_block(_T_ENDIF,
+                                  node,             # parent
+                                  visible_if_deps,
+                                  node)             # prev_node
+                node.list = node.next
+
+                prev_node.next = prev_node = node
+
+            elif t0 == _T_MENU:
+                node = MenuNode()
+                node.kconfig = self
+                node.item = MENU
+                node.visibility = self.y
+                node.parent = parent
+                node.filename = self._filename
+                node.linenr = self._linenr
+
+                prompt = self._next_token()
+                self._parse_properties(node, visible_if_deps)
+                node.prompt = (prompt, node.dep)
+
+                self._parse_block(_T_ENDMENU,
+                                  node,         # parent
+                                  self._make_and(visible_if_deps,
+                                                 node.visibility),
+                                  node)         # prev_node
+                node.list = node.next
+
+                prev_node.next = prev_node = node
+
+            elif t0 == _T_COMMENT:
+                node = MenuNode()
+                node.kconfig = self
+                node.item = COMMENT
+                node.list = None
+                node.parent = parent
+                node.filename = self._filename
+                node.linenr = self._linenr
+
+                prompt = self._next_token()
+                self._parse_properties(node, visible_if_deps)
+                node.prompt = (prompt, node.dep)
+
+                prev_node.next = prev_node = node
+
+            elif t0 == _T_CHOICE:
+                name = self._next_token()
+                if name is None:
+                    choice = Choice()
+                    self._choices.append(choice)
+                else:
+                    # Named choice
+                    choice = self.named_choices.get(name)
+                    if not choice:
+                        choice = Choice()
+                        self._choices.append(choice)
+                        choice.name = name
+                        self.named_choices[name] = choice
+
+                choice.kconfig = self
+
+                node = MenuNode()
+                node.kconfig = self
+                node.item = choice
+                node.help = None
+                node.parent = parent
+                node.filename = self._filename
+                node.linenr = self._linenr
+
+                self._parse_properties(node, visible_if_deps)
+                self._parse_block(_T_ENDCHOICE,
+                                  node,             # parent
+                                  visible_if_deps,
+                                  node)             # prev_node
+                node.list = node.next
+
+                choice.nodes.append(node)
+
+                prev_node.next = prev_node = node
+
+            elif t0 == _T_MAINMENU:
+                self.top_node.prompt = (self._next_token(), self.y)
+                self.top_node.filename = self._filename
+                self.top_node.linenr = self._linenr
+
+            else:
+                self._parse_error("unrecognized construct")
+
+        # End of file reached. Terminate the final node and return it.
+
+        if end_token is not None:
+            raise KconfigSyntaxError("Unexpected end of file " +
+                                     self._filename)
+
+        prev_node.next = None
+        return prev_node
+
+    def _parse_cond(self):
+        """
+        Parses an optional 'if <expr>' construct and returns the parsed <expr>,
+        or self.y if the next token is not _T_IF
+        """
+        return self._parse_expr(True) if self._check_token(_T_IF) else self.y
+
+    def _parse_properties(self, node, visible_if_deps):
+        """
+        Parses properties for symbols, menus, choices, and comments. Also takes
+        care of propagating dependencies from the menu node to the properties
+        of the item (this mirrors the C tools, though they do it after
+        parsing).
+
+        node:
+          The menu node we're parsing properties on. Prompt, help text,
+          'depends on', and 'visible if' properties apply to the Menu node,
+          while the others apply to the contained item.
+
+        visible_if_deps:
+          'visible if' dependencies from enclosing menus. Propagated to Symbol
+          and Choice prompts.
+        """
+        # New properties encountered at this location. A local 'depends on'
+        # only applies to these, in case a symbol is defined in multiple
+        # locations.
+        prompt = None
+        defaults = []
+        selects = []
+        implies = []
+        ranges = []
+
+        # Menu node dependencies from 'depends on'. Will get propagated to the
+        # properties above.
+        node.dep = self.y
+
+        while self._next_line():
+            t0 = self._next_token()
+            if t0 is None:
+                continue
+
+            if t0 in _TYPE_TOKENS:
+                node.item.orig_type = _TOKEN_TO_TYPE[t0]
+
+                if self._peek_token() is not None:
+                    prompt = (self._next_token(), self._parse_cond())
+
+            elif t0 == _T_DEPENDS:
+                if not self._check_token(_T_ON):
+                    self._parse_error('expected "on" after "depends"')
+
+                node.dep = self._make_and(node.dep, self._parse_expr(True))
+
+            elif t0 == _T_HELP:
+                # Find first non-blank (not all-space) line and get its
+                # indentation
+
+                while 1:
+                    line = self._next_help_line()
+                    if not line or not line.isspace():
+                        break
+
+                if not line:
+                    node.help = ""
+                    break
+
+                indent = _indentation(line)
+                if indent == 0:
+                    # If the first non-empty lines has zero indent, there is no
+                    # help text
+                    node.help = ""
+                    self._reuse_line = True  # "Unget" the line
+                    break
+
+                # The help text goes on till the first non-empty line with less
+                # indent
+
+                help_lines = [_deindent(line, indent).rstrip()]
+                while 1:
+                    line = self._next_help_line()
+
+                    if not line or \
+                       (not line.isspace() and _indentation(line) < indent):
+                        node.help = "\n".join(help_lines).rstrip() + "\n"
+                        break
+
+                    help_lines.append(_deindent(line, indent).rstrip())
+
+                if not line:
+                    break
+
+                self._reuse_line = True  # "Unget" the line
+
+            elif t0 == _T_SELECT:
+                if not isinstance(node.item, Symbol):
+                    self._parse_error("only symbols can select")
+
+                selects.append((self._next_token(), self._parse_cond()))
+
+            elif t0 == _T_IMPLY:
+                if not isinstance(node.item, Symbol):
+                    self._parse_error("only symbols can imply")
+
+                implies.append((self._next_token(), self._parse_cond()))
+
+            elif t0 == _T_DEFAULT:
+                defaults.append((self._parse_expr(False), self._parse_cond()))
+
+            elif t0 in (_T_DEF_BOOL, _T_DEF_TRISTATE):
+                node.item.orig_type = _TOKEN_TO_TYPE[t0]
+                defaults.append((self._parse_expr(False), self._parse_cond()))
+
+            elif t0 == _T_PROMPT:
+                # 'prompt' properties override each other within a single
+                # definition of a symbol, but additional prompts can be added
+                # by defining the symbol multiple times
+                prompt = (self._next_token(), self._parse_cond())
+
+            elif t0 == _T_RANGE:
+                ranges.append((self._next_token(),
+                               self._next_token(),
+                               self._parse_cond()))
+
+            elif t0 == _T_OPTION:
+                if self._check_token(_T_ENV):
+                    if not self._check_token(_T_EQUAL):
+                        self._parse_error("expected '=' after 'env'")
+
+                    env_var = self._next_token()
+                    node.item.env_var = env_var
+
+                    if env_var not in os.environ:
+                        self._warn("'option env=\"{0}\"' on symbol {1} has "
+                                   "no effect, because the environment "
+                                   "variable {0} is not set"
+                                   .format(env_var, node.item.name),
+                                   self._filename, self._linenr)
+                    else:
+                        defaults.append(
+                            (self._lookup_const_sym(os.environ[env_var]),
+                             self.y))
+
+                elif self._check_token(_T_DEFCONFIG_LIST):
+                    if not self.defconfig_list:
+                        self.defconfig_list = node.item
+                    else:
+                        self._warn("'option defconfig_list' set on multiple "
+                                   "symbols ({0} and {1}). Only {0} will be "
+                                   "used.".format(self.defconfig_list.name,
+                                                  node.item.name),
+                                   self._filename, self._linenr)
+
+                elif self._check_token(_T_MODULES):
+                    # To reduce warning spam, only warn if 'option modules' is
+                    # set on some symbol that isn't MODULES, which should be
+                    # safe. I haven't run into any projects that make use
+                    # modules besides the kernel yet, and there it's likely to
+                    # keep being called "MODULES".
+                    if node.item is not self.modules:
+                        self._warn("the 'modules' option is not supported. "
+                                   "Let me know if this is a problem for you, "
+                                   "as it wouldn't be that hard to implement. "
+                                   "Note that modules are supported -- "
+                                   "Kconfiglib just assumes the symbol name "
+                                   "MODULES, like older versions of the C "
+                                   "implementation did when 'option modules' "
+                                   "wasn't used.",
+                                   self._filename, self._linenr)
+
+                elif self._check_token(_T_ALLNOCONFIG_Y):
+                    if not isinstance(node.item, Symbol):
+                        self._parse_error("the 'allnoconfig_y' option is only "
+                                          "valid for symbols")
+
+                    node.item.is_allnoconfig_y = True
+
+                else:
+                    self._parse_error("unrecognized option")
+
+            elif t0 == _T_VISIBLE:
+                if not self._check_token(_T_IF):
+                    self._parse_error('expected "if" after "visible"')
+
+                node.visibility = \
+                    self._make_and(node.visibility, self._parse_expr(True))
+
+            elif t0 == _T_OPTIONAL:
+                if not isinstance(node.item, Choice):
+                    self._parse_error('"optional" is only valid for choices')
+
+                node.item.is_optional = True
+
+            else:
+                self._tokens_i = -1
+                # Reuse the tokens for the non-property line later
+                self._has_tokens = True
+                break
+
+        # Done parsing properties. Now add the new
+        # prompts/defaults/selects/implies/ranges properties, with dependencies
+        # from node.dep propagated.
+
+        # First propagate parent dependencies to node.dep
+
+        # If the parent node holds a Choice, we use the Choice itself as the
+        # parent dependency. This matches the C implementation, and makes sense
+        # as the value (mode) of the choice limits the visibility of the
+        # contained choice symbols. Due to the similar interface, Choice works
+        # as a drop-in replacement for Symbol here.
+        if isinstance(node.parent.item, Choice):
+            node.dep = self._make_and(node.dep, node.parent.item)
+        else:
+            node.dep = self._make_and(node.dep, node.parent.dep)
+
+        if isinstance(node.item, (Symbol, Choice)):
+            if isinstance(node.item, Symbol):
+                # See the class documentation
+                node.item.direct_dep = \
+                    self._make_or(node.item.direct_dep, node.dep)
+
+            # Set the prompt, with dependencies propagated
+            if prompt:
+                node.prompt = (prompt[0],
+                               self._make_and(self._make_and(prompt[1],
+                                                             node.dep),
+                                              visible_if_deps))
+            else:
+                node.prompt = None
+
+            # Add the new defaults, with dependencies propagated
+            for val_expr, cond in defaults:
+                node.item.defaults.append(
+                    (val_expr, self._make_and(cond, node.dep)))
+
+            # Add the new ranges, with dependencies propagated
+            for low, high, cond in ranges:
+                node.item.ranges.append(
+                    (low, high, self._make_and(cond, node.dep)))
+
+            # Handle selects
+            for target, cond in selects:
+                # Only stored for inspection. Not used during evaluation.
+                node.item.selects.append(
+                    (target, self._make_and(cond, node.dep)))
+
+                # Modify the dependencies of the selected symbol
+                target.rev_dep = \
+                    self._make_or(target.rev_dep,
+                                  self._make_and(node.item,
+                                                 self._make_and(cond,
+                                                                node.dep)))
+
+            # Handle implies
+            for target, cond in implies:
+                # Only stored for inspection. Not used during evaluation.
+                node.item.implies.append(
+                    (target, self._make_and(cond, node.dep)))
+
+                # Modify the dependencies of the implied symbol
+                target.weak_rev_dep = \
+                    self._make_or(target.weak_rev_dep,
+                                  self._make_and(node.item,
+                                                 self._make_and(cond,
+                                                                node.dep)))
+
+    def _parse_expr(self, transform_m):
+        """
+        Parses an expression from the tokens in Kconfig._tokens using a simple
+        top-down approach. See the module docs for the expression format.
+
+        transform_m:
+          True if m should be rewritten to m && MODULES. See the
+          Kconfig.eval_string() documentation.
+        """
+        # Grammar:
+        #
+        #   expr:     and_expr ['||' expr]
+        #   and_expr: factor ['&&' and_expr]
+        #   factor:   <symbol> ['='/'!='/'<'/... <symbol>]
+        #             '!' factor
+        #             '(' expr ')'
+        #
+        # It helps to think of the 'expr: and_expr' case as a single-operand OR
+        # (no ||), and of the 'and_expr: factor' case as a single-operand AND
+        # (no &&). Parsing code is always a bit tricky.
+
+        # Mind dump: parse_factor() and two nested loops for OR and AND would
+        # work as well. The straightforward implementation there gives a
+        # (op, (op, (op, A, B), C), D) parse for A op B op C op D. Representing
+        # expressions as (op, [list of operands]) instead goes nicely with that
+        # version, but is wasteful for short expressions and complicates
+        # expression evaluation and other code that works on expressions (more
+        # complicated code likely offsets any performance gain from less
+        # recursion too). If we also try to optimize the list representation by
+        # merging lists when possible (e.g. when ANDing two AND expressions),
+        # we end up allocating a ton of lists instead of reusing expressions,
+        # which is bad.
+
+        and_expr = self._parse_and_expr(transform_m)
+
+        # Return 'and_expr' directly if we have a "single-operand" OR.
+        # Otherwise, parse the expression on the right and make an OR node.
+        # This turns A || B || C || D into (OR, A, (OR, B, (OR, C, D))).
+        return and_expr \
+               if not self._check_token(_T_OR) else \
+               (OR, and_expr, self._parse_expr(transform_m))
+
+    def _parse_and_expr(self, transform_m):
+        factor = self._parse_factor(transform_m)
+
+        # Return 'factor' directly if we have a "single-operand" AND.
+        # Otherwise, parse the right operand and make an AND node. This turns
+        # A && B && C && D into (AND, A, (AND, B, (AND, C, D))).
+        return factor \
+               if not self._check_token(_T_AND) else \
+               (AND, factor, self._parse_and_expr(transform_m))
+
+    def _parse_factor(self, transform_m):
+        token = self._next_token()
+
+        if isinstance(token, Symbol):
+            # Plain symbol or relation
+
+            next_token = self._peek_token()
+            if next_token not in _TOKEN_TO_REL:
+                # Plain symbol
+
+                # For conditional expressions ('depends on <expr>',
+                # '... if <expr>', etc.), m is rewritten to m && MODULES.
+                if transform_m and token is self.m:
+                    return (AND, self.m, self.modules)
+
+                return token
+
+            # Relation
+            return (_TOKEN_TO_REL[self._next_token()], token,
+                    self._next_token())
+
+        if token == _T_NOT:
+            return (NOT, self._parse_factor(transform_m))
+
+        if token == _T_OPEN_PAREN:
+            expr_parse = self._parse_expr(transform_m)
+            if not self._check_token(_T_CLOSE_PAREN):
+                self._parse_error("missing end parenthesis")
+
+            return expr_parse
+
+        self._parse_error("malformed expression")
+
+    #
+    # Caching and invalidation
+    #
+
+    def _build_dep(self):
+        """
+        Populates the Symbol/Choice._dependents sets, which contain all other
+        items (symbols and choices) that immediately depend on the item in the
+        sense that changing the value of the item might affect the value of the
+        dependent items. This is used for caching/invalidation.
+
+        The calculated sets might be larger than necessary as we don't do any
+        complex analysis of the expressions.
+        """
+        # Only calculate _dependents for defined symbols. Constant and
+        # undefined symbols could theoretically be selected/implied, but it
+        # wouldn't change their value, so it's not a true dependency.
+        for sym in self.defined_syms:
+            # Symbols depend on the following:
+
+            # The prompt conditions
+            for node in sym.nodes:
+                if node.prompt:
+                    _make_depend_on(sym, node.prompt[1])
+
+            # The default values and their conditions
+            for value, cond in sym.defaults:
+                _make_depend_on(sym, value)
+                _make_depend_on(sym, cond)
+
+            # The reverse and weak reverse dependencies
+            _make_depend_on(sym, sym.rev_dep)
+            _make_depend_on(sym, sym.weak_rev_dep)
+
+            # The ranges along with their conditions
+            for low, high, cond in sym.ranges:
+                _make_depend_on(sym, low)
+                _make_depend_on(sym, high)
+                _make_depend_on(sym, cond)
+
+            # The direct dependencies. This is usually redundant, as the direct
+            # dependencies get propagated to properties, but it's needed to get
+            # invalidation solid for 'imply', which only checks the direct
+            # dependencies (even if there are no properties to propagate it
+            # to).
+            _make_depend_on(sym, sym.direct_dep)
+
+            # In addition to the above, choice symbols depend on the choice
+            # they're in, but that's handled automatically since the Choice is
+            # propagated to the conditions of the properties before
+            # _build_dep() runs.
+
+        for choice in self._choices:
+            # Choices depend on the following:
+
+            # The prompt conditions
+            for node in choice.nodes:
+                if node.prompt:
+                    _make_depend_on(choice, node.prompt[1])
+
+            # The default symbol conditions
+            for _, cond in choice.defaults:
+                _make_depend_on(choice, cond)
+
+            # The choice symbols themselves, because the y mode selection might
+            # change if a choice symbol's visibility changes
+            for sym in choice.syms:
+                # the default selection depends on the symbols
+                sym._dependents.add(choice)
+
+    def _invalidate_all(self):
+        # Undefined symbols never change value and don't need to be
+        # invalidated, so we can just iterate over defined symbols.
+        # Invalidating constant symbols would break things horribly.
+        for sym in self.defined_syms:
+            sym._invalidate()
+
+        for choice in self._choices:
+            choice._invalidate()
+
+
+    #
+    # Misc.
+    #
+
+    def _expand_syms(self, s):
+        """
+        Expands $-references to symbols in 's' to symbol values, or to the
+        empty string for undefined symbols.
+        """
+        while 1:
+            sym_ref_match = _sym_ref_re_search(s)
+            if not sym_ref_match:
+                return s
+
+            sym = self.syms.get(sym_ref_match.group(1))
+
+            s = s[:sym_ref_match.start()] + \
+                (sym.str_value if sym else "") + \
+                s[sym_ref_match.end():]
+
+    def _parse_error(self, msg):
+        if self._filename is None:
+            loc = ""
+        else:
+            loc = "{}:{}: ".format(self._filename, self._linenr)
+
+        raise KconfigSyntaxError(
+            "{}Couldn't parse '{}': {}".format(loc, self._line.rstrip(), msg))
+
+    def _warn(self, msg, filename=None, linenr=None):
+        """
+        For printing general warnings.
+        """
+        if self._print_warnings:
+            _stderr_msg("warning: " + msg, filename, linenr)
+
+    def _warn_undef_assign(self, msg, filename=None, linenr=None):
+        """
+        See the class documentation.
+        """
+        if self._print_undef_assign:
+            _stderr_msg("warning: " + msg, filename, linenr)
+
+    def _warn_undef_assign_load(self, name, val, filename, linenr):
+        """
+        Special version for load_config().
+        """
+        self._warn_undef_assign(
+            'attempt to assign the value "{}" to the undefined symbol {}' \
+            .format(val, name), filename, linenr)
+
+
+class Symbol(object):
+    """
+    Represents a configuration symbol:
+
+      (menu)config FOO
+          ...
+
+    The following attributes are available. They should be viewed as read-only,
+    and some are implemented through @property magic (but are still efficient
+    to access due to internal caching).
+
+    Note: Prompts, help texts, and locations are stored in the Symbol's
+    MenuNode(s) rather than in the Symbol itself. Check the MenuNode class and
+    the Symbol.nodes attribute. This organization matches the C tools.
+
+    name:
+      The name of the symbol, e.g. "FOO" for 'config FOO'.
+
+    type:
+      The type of the symbol. One of BOOL, TRISTATE, STRING, INT, HEX, UNKNOWN.
+      UNKNOWN is for undefined symbols, (non-special) constant symbols, and
+      symbols defined without a type.
+
+      When running without modules (MODULES having the value n), TRISTATE
+      symbols magically change type to BOOL. This also happens for symbols
+      within choices in "y" mode. This matches the C tools, and makes sense for
+      menuconfig-like functionality.
+
+    orig_type:
+      The type as given in the Kconfig file, without any magic applied. Used
+      when printing the symbol.
+
+    str_value:
+      The value of the symbol as a string. Gives the value for string/int/hex
+      symbols. For bool/tristate symbols, gives "n", "m", or "y".
+
+      This is the symbol value that's used in relational expressions
+      (A = B, A != B, etc.)
+
+      Gotcha: For int/hex symbols, the exact format of the value must often be
+      preserved (e.g., when writing a .config file), hence why you can't get it
+      directly as an int. Do int(int_sym.str_value) or
+      int(hex_sym.str_value, 16) to get the integer value.
+
+    tri_value:
+      The tristate value of the symbol as an integer. One of 0, 1, 2,
+      representing n, m, y. Always 0 (n) for non-bool/tristate symbols.
+
+      This is the symbol value that's used outside of relation expressions
+      (A, !A, A && B, A || B).
+
+    assignable:
+      A tuple containing the tristate user values that can currently be
+      assigned to the symbol (that would be respected), ordered from lowest (0,
+      representing n) to highest (2, representing y). This corresponds to the
+      selections available in the menuconfig interface. The set of assignable
+      values is calculated from the symbol's visibility and selects/implies.
+
+      Returns the empty set for non-bool/tristate symbols and for symbols with
+      visibility n. The other possible values are (0, 2), (0, 1, 2), (1, 2),
+      (1,), and (2,). A (1,) or (2,) result means the symbol is visible but
+      "locked" to m or y through a select, perhaps in combination with the
+      visibility. menuconfig represents this as -M- and -*-, respectively.
+
+      For string/hex/int symbols, check if Symbol.visibility is non-0 (non-n)
+      instead to determine if the value can be changed.
+
+      Some handy 'assignable' idioms:
+
+        # Is 'sym' an assignable (visible) bool/tristate symbol?
+        if sym.assignable:
+            # What's the highest value it can be assigned? [-1] in Python
+            # gives the last element.
+            sym_high = sym.assignable[-1]
+
+            # The lowest?
+            sym_low = sym.assignable[0]
+
+            # Can the symbol be set to at least m?
+            if sym.assignable[-1] >= 1:
+                ...
+
+        # Can the symbol be set to m?
+        if 1 in sym.assignable:
+            ...
+
+    visibility:
+      The visibility of the symbol. One of 0, 1, 2, representing n, m, y. See
+      the module documentation for an overview of symbol values and visibility.
+
+    user_value:
+      The user value of the symbol. None if no user value has been assigned
+      (via Kconfig.load_config() or Symbol.set_value()).
+
+      Holds 0, 1, or 2 for bool/tristate symbols, and a string for the other
+      symbol types.
+
+      WARNING: Do not assign directly to this. It will break things. Use
+      Symbol.set_value().
+
+    config_string:
+      The .config assignment string that would get written out for the symbol
+      by Kconfig.write_config(). None if no .config assignment would get
+      written out. In general, visible symbols, symbols with (active) defaults,
+      and selected symbols get written out.
+
+    nodes:
+      A list of MenuNodes for this symbol. Will contain a single MenuNode for
+      most symbols. Undefined and constant symbols have an empty nodes list.
+      Symbols defined in multiple locations get one node for each location.
+
+    choice:
+      Holds the parent Choice for choice symbols, and None for non-choice
+      symbols. Doubles as a flag for whether a symbol is a choice symbol.
+
+    defaults:
+      List of (default, cond) tuples for the symbol's 'default' properties. For
+      example, 'default A && B if C || D' is represented as
+      ((AND, A, B), (OR, C, D)). If no condition was given, 'cond' is
+      self.kconfig.y.
+
+      Note that 'depends on' and parent dependencies are propagated to
+      'default' conditions.
+
+    selects:
+      List of (symbol, cond) tuples for the symbol's 'select' properties. For
+      example, 'select A if B && C' is represented as (A, (AND, B, C)). If no
+      condition was given, 'cond' is self.kconfig.y.
+
+      Note that 'depends on' and parent dependencies are propagated to 'select'
+      conditions.
+
+    implies:
+      Like 'selects', for imply.
+
+    ranges:
+      List of (low, high, cond) tuples for the symbol's 'range' properties. For
+      example, 'range 1 2 if A' is represented as (1, 2, A). If there is no
+      condition, 'cond' is self.config.y.
+
+      Note that 'depends on' and parent dependencies are propagated to 'range'
+      conditions.
+
+      Gotcha: 1 and 2 above will be represented as (undefined) Symbols rather
+      than plain integers. Undefined symbols get their name as their string
+      value, so this works out. The C tools work the same way.
+
+    rev_dep:
+      Reverse dependency expression from other symbols selecting this symbol.
+      Multiple selections get ORed together. A condition on a select is ANDed
+      with the selecting symbol.
+
+      For example, if A has 'select FOO' and B has 'select FOO if C', then
+      FOO's rev_dep will be (OR, A, (AND, B, C)).
+
+    weak_rev_dep:
+      Like rev_dep, for imply.
+
+    direct_dep:
+      The 'depends on' dependencies. If a symbol is defined in multiple
+      locations, the dependencies at each location are ORed together.
+
+      Internally, this is only used to implement 'imply', which only applies if
+      the implied symbol has expr_value(self.direct_dep) != 0. 'depends on' and
+      parent dependencies are automatically propagated to the conditions of
+      properties, so normally it's redundant to check the direct dependencies.
+
+    env_var:
+      If the Symbol has an 'option env="FOO"' option, this contains the name
+      ("FOO") of the environment variable. None for symbols that aren't set
+      from the environment.
+
+      'option env="FOO"' acts as a 'default' property whose value is the value
+      of $FOO.
+
+      env_var is set to "<uname release>" for the predefined symbol
+      UNAME_RELEASE, which holds the 'release' field from uname.
+
+      Symbols with an 'option env' option are never written out to .config
+      files, even if they are visible. env_var corresponds to a flag called
+      SYMBOL_AUTO in the C implementation.
+
+    is_allnoconfig_y:
+      True if the symbol has 'option allnoconfig_y' set on it. This has no
+      effect internally (except when printing symbols), but can be checked by
+      scripts.
+
+    is_constant:
+      True if the symbol is a constant (quoted) symbol.
+
+    kconfig:
+      The Kconfig instance this symbol is from.
+    """
+    __slots__ = (
+        "_cached_assignable",
+        "_cached_str_val",
+        "_cached_tri_val",
+        "_cached_vis",
+        "_dependents",
+        "_was_set",
+        "_write_to_conf",
+        "choice",
+        "defaults",
+        "direct_dep",
+        "env_var",
+        "implies",
+        "is_allnoconfig_y",
+        "is_constant",
+        "kconfig",
+        "name",
+        "nodes",
+        "orig_type",
+        "ranges",
+        "rev_dep",
+        "selects",
+        "user_value",
+        "weak_rev_dep",
+    )
+
+    #
+    # Public interface
+    #
+
+    @property
+    def type(self):
+        """
+        See the class documentation.
+        """
+        if self.orig_type == TRISTATE and \
+           ((self.choice and self.choice.tri_value == 2) or
+            not self.kconfig.modules.tri_value):
+            return BOOL
+
+        return self.orig_type
+
+    @property
+    def str_value(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_str_val is not None:
+            return self._cached_str_val
+
+        if self.orig_type in (BOOL, TRISTATE):
+            # Also calculates the visibility, so invalidation safe
+            self._cached_str_val = TRI_TO_STR[self.tri_value]
+            return self._cached_str_val
+
+        # As a quirk of Kconfig, undefined symbols get their name as their
+        # string value. This is why things like "FOO = bar" work for seeing if
+        # FOO has the value "bar".
+        if self.orig_type == UNKNOWN:
+            self._cached_str_val = self.name
+            return self.name
+
+        val = ""
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        vis = self.visibility
+
+        self._write_to_conf = (vis != 0)
+
+        if self.orig_type in (INT, HEX):
+            # The C implementation checks the user value against the range in a
+            # separate code path (post-processing after loading a .config).
+            # Checking all values here instead makes more sense for us. It
+            # requires that we check for a range first.
+
+            base = _TYPE_TO_BASE[self.orig_type]
+
+            # Check if a range is in effect
+            for low_expr, high_expr, cond in self.ranges:
+                if expr_value(cond):
+                    has_active_range = True
+
+                    # The zeros are from the C implementation running strtoll()
+                    # on empty strings
+                    low = int(low_expr.str_value, base) if \
+                      _is_base_n(low_expr.str_value, base) else 0
+                    high = int(high_expr.str_value, base) if \
+                      _is_base_n(high_expr.str_value, base) else 0
+
+                    break
+            else:
+                has_active_range = False
+
+            if vis and self.user_value is not None and \
+               _is_base_n(self.user_value, base) and \
+               (not has_active_range or
+                low <= int(self.user_value, base) <= high):
+
+                # If the user value is well-formed and satisfies range
+                # contraints, it is stored in exactly the same form as
+                # specified in the assignment (with or without "0x", etc.)
+                val = self.user_value
+
+            else:
+                # No user value or invalid user value. Look at defaults.
+
+                for val_expr, cond in self.defaults:
+                    if expr_value(cond):
+                        self._write_to_conf = True
+
+                        val = val_expr.str_value
+
+                        if _is_base_n(val, base):
+                            val_num = int(val, base)
+                        else:
+                            val_num = 0  # strtoll() on empty string
+
+                        break
+                else:
+                    val_num = 0  # strtoll() on empty string
+
+                # This clamping procedure runs even if there's no default
+                if has_active_range:
+                    clamp = None
+                    if val_num < low:
+                        clamp = low
+                    elif val_num > high:
+                        clamp = high
+
+                    if clamp is not None:
+                        # The value is rewritten to a standard form if it is
+                        # clamped
+                        val = str(clamp) \
+                              if self.orig_type == INT else \
+                              hex(clamp)
+
+        elif self.orig_type == STRING:
+            if vis and self.user_value is not None:
+                # If the symbol is visible and has a user value, use that
+                val = self.user_value
+            else:
+                # Otherwise, look at defaults
+                for val_expr, cond in self.defaults:
+                    if expr_value(cond):
+                        self._write_to_conf = True
+                        val = val_expr.str_value
+                        break
+
+        # Corresponds to SYMBOL_AUTO in the C implementation
+        if self.env_var is not None:
+            self._write_to_conf = False
+
+        self._cached_str_val = val
+        return val
+
+    @property
+    def tri_value(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_tri_val is not None:
+            return self._cached_tri_val
+
+        if self.orig_type not in (BOOL, TRISTATE):
+            self._cached_tri_val = 0
+            return self._cached_tri_val
+
+        val = 0
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        vis = self.visibility
+        self._write_to_conf = (vis != 0)
+
+        if not self.choice:
+            # Non-choice symbol
+
+            if vis and self.user_value is not None:
+                # If the symbol is visible and has a user value, use that
+                val = min(self.user_value, vis)
+
+            else:
+                # Otherwise, look at defaults and weak reverse dependencies
+                # (implies)
+
+                for default, cond in self.defaults:
+                    cond_val = expr_value(cond)
+                    if cond_val:
+                        val = min(expr_value(default), cond_val)
+                        self._write_to_conf = True
+                        break
+
+                # Weak reverse dependencies are only considered if our
+                # direct dependencies are met
+                weak_rev_dep_val = expr_value(self.weak_rev_dep)
+                if weak_rev_dep_val and expr_value(self.direct_dep):
+                    val = max(weak_rev_dep_val, val)
+                    self._write_to_conf = True
+
+            # Reverse (select-related) dependencies take precedence
+            rev_dep_val = expr_value(self.rev_dep)
+            if rev_dep_val:
+                val = max(rev_dep_val, val)
+                self._write_to_conf = True
+
+            # m is promoted to y for (1) bool symbols and (2) symbols with a
+            # weak_rev_dep (from imply) of y
+            if val == 1 and \
+               (self.type == BOOL or expr_value(self.weak_rev_dep) == 2):
+                val = 2
+
+        elif vis == 2:
+            # Visible choice symbol in y-mode choice. The choice mode limits
+            # the visibility of choice symbols, so it's sufficient to just
+            # check the visibility of the choice symbols themselves.
+            val = 2 if self.choice.selection is self else 0
+
+        elif vis and self.user_value:
+            # Visible choice symbol in m-mode choice, with set non-0 user value
+            val = 1
+
+        self._cached_tri_val = val
+        return val
+
+    @property
+    def assignable(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_assignable is not None:
+            return self._cached_assignable
+
+        self._cached_assignable = self._get_assignable()
+        return self._cached_assignable
+
+    @property
+    def visibility(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_vis is not None:
+            return self._cached_vis
+
+        self._cached_vis = _get_visibility(self)
+        return self._cached_vis
+
+    @property
+    def config_string(self):
+        """
+        See the class documentation.
+        """
+        # Note: _write_to_conf is determined when the value is calculated. This
+        # is a hidden function call due to property magic.
+        val = self.str_value
+        if not self._write_to_conf:
+            return None
+
+        if self.orig_type in (BOOL, TRISTATE):
+            return "{}{}={}\n" \
+                   .format(self.kconfig.config_prefix, self.name, val) \
+                   if val != "n" else \
+                   "# {}{} is not set\n" \
+                   .format(self.kconfig.config_prefix, self.name)
+
+        if self.orig_type in (INT, HEX):
+            return "{}{}={}\n" \
+                   .format(self.kconfig.config_prefix, self.name, val)
+
+        if self.orig_type == STRING:
+            # Escape \ and "
+            return '{}{}="{}"\n' \
+                   .format(self.kconfig.config_prefix, self.name, escape(val))
+
+        _internal_error("Internal error while creating .config: unknown "
+                        'type "{}".'.format(self.orig_type))
+
+    def set_value(self, value):
+        """
+        Sets the user value of the symbol.
+
+        Equal in effect to assigning the value to the symbol within a .config
+        file. For bool and tristate symbols, use the 'assignable' attribute to
+        check which values can currently be assigned. Setting values outside
+        'assignable' will cause Symbol.user_str/tri_value to differ from
+        Symbol.str/tri_value (be truncated down or up).
+
+        Setting a choice symbol to 2 (y) only updates Choice.user_selection on
+        the parent choice and not Symbol.user_value itself. This gives the
+        expected behavior when a choice is switched between different modes.
+        Choice.user_selection is considered when the choice is in y mode (the
+        "normal" mode).
+
+        Other symbols that depend (possibly indirectly) on this symbol are
+        automatically recalculated to reflect the assigned value.
+
+        value:
+          The user value to give to the symbol. For bool and tristate symbols,
+          pass 0, 1, 2 for n, m, and y, respectively. For other symbol types,
+          pass a string.
+
+          Values that are invalid for the type (such as "foo" or 1 (m) for a
+          BOOL) are ignored and won't be stored in Symbol.user_str/tri_value.
+          Kconfiglib will print a warning by default for invalid assignments,
+          and set_value() will return False.
+
+        Returns True if the value is valid for the type of the symbol, and
+        False otherwise. This only looks at the form of the value. For BOOL and
+        TRISTATE symbols, check the Symbol.assignable attribute to see what
+        values are currently in range and would actually be reflected in the
+        value of the symbol. For other symbol types, check whether the
+        visibility is non-n.
+        """
+        if value == self.user_value:
+            # We know the value must be valid if it was successfully set
+            # previously
+            self._was_set = True
+            return True
+
+        # Check if the value is valid for our type
+        if not ((self.orig_type == BOOL     and value in (0, 2)       ) or
+                (self.orig_type == TRISTATE and value in (0, 1, 2)    ) or
+                (self.orig_type == STRING   and isinstance(value, str)) or
+                (self.orig_type == INT      and isinstance(value, str)
+                                            and _is_base_n(value, 10) ) or
+                (self.orig_type == HEX      and isinstance(value, str)
+                                            and _is_base_n(value, 16)
+                                            and int(value, 16) >= 0)):
+
+            # Display tristate values as n, m, y in the warning
+            warning = "the value {} is invalid for {}, which has type {}" \
+                      .format(TRI_TO_STR[value] if value in (0, 1, 2) else
+                                 "'{}'".format(value),
+                              self.name, TYPE_TO_STR[self.orig_type])
+
+            if self.orig_type in (BOOL, TRISTATE) and value in ("n", "m", "y"):
+                warning += ' (pass 0, 1, 2 for n, m, y, respectively)'
+
+            self.kconfig._warn(warning)
+
+            return False
+
+        if self.env_var is not None:
+            self.kconfig._warn("ignored attempt to assign user value to "
+                               "{}, which gets its value from the environment"
+                               .format(self.name))
+            return False
+
+        if self.choice and value == 2:
+            # Remember this as a choice selection only. Makes switching back
+            # and forth between choice modes work as expected, and makes the
+            # check for whether the user value is the same as before above
+            # safe.
+            self.choice.user_selection = self
+            self.choice._was_set = True
+            if self._is_user_assignable():
+                self.choice._rec_invalidate()
+        else:
+            self.user_value = value
+            self._was_set = True
+            if self._is_user_assignable():
+                self._rec_invalidate()
+
+        return True
+
+    def unset_value(self):
+        """
+        Resets the user value of the symbol, as if the symbol had never gotten
+        a user value via Kconfig.load_config() or Symbol.set_value().
+        """
+        if self.user_value is not None:
+            self.user_value = None
+            if self._is_user_assignable():
+                self._rec_invalidate()
+
+    def __repr__(self):
+        """
+        Returns a string with information about the symbol (including its name,
+        value, visibility, and location(s)) when it is evaluated on e.g. the
+        interactive Python prompt.
+        """
+        fields = []
+
+        fields.append("symbol " + self.name)
+        fields.append(TYPE_TO_STR[self.type])
+
+        for node in self.nodes:
+            if node.prompt:
+                fields.append('"{}"'.format(node.prompt[0]))
+
+        # Only add quotes for non-bool/tristate symbols
+        fields.append("value " +
+                      (self.str_value
+                       if self.orig_type in (BOOL, TRISTATE) else
+                       '"{}"'.format(self.str_value)))
+
+        if not self.is_constant:
+            # These aren't helpful to show for constant symbols
+
+            if self.user_value is not None:
+                # Only add quotes for non-bool/tristate symbols
+                fields.append("user value " +
+                              (TRI_TO_STR[self.user_value]
+                               if self.orig_type in (BOOL, TRISTATE) else
+                               '"{}"'.format(self.user_value)))
+
+            fields.append("visibility " + TRI_TO_STR[self.visibility])
+
+            if self.choice:
+                fields.append("choice symbol")
+
+            if self.is_allnoconfig_y:
+                fields.append("allnoconfig_y")
+
+            if self is self.kconfig.defconfig_list:
+                fields.append("is the defconfig_list symbol")
+
+            if self.env_var is not None:
+                fields.append("from environment variable " + self.env_var)
+
+            if self is self.kconfig.modules:
+                fields.append("is the modules symbol")
+
+            fields.append("direct deps " +
+                          TRI_TO_STR[expr_value(self.direct_dep)])
+
+        if self.nodes:
+            for node in self.nodes:
+                fields.append("{}:{}".format(node.filename, node.linenr))
+        else:
+            if self.is_constant:
+                fields.append("constant")
+            else:
+                fields.append("undefined")
+
+        return "<{}>".format(", ".join(fields))
+
+    def __str__(self):
+        """
+        Returns a string representation of the symbol when it is printed,
+        matching the Kconfig format. Prompts and help texts are included,
+        though they really belong to the symbol's menu nodes rather than the
+        symbol itself.
+
+        The output is designed so that feeding it back to a Kconfig parser
+        redefines the symbol as is. This also works for symbols defined in
+        multiple locations, where all the definitions are output. See the
+        module documentation for a small gotcha related to choice symbols.
+
+        An empty string is returned for undefined and constant symbols.
+        """
+        return _sym_choice_str(self)
+
+    #
+    # Private methods
+    #
+
+    def __init__(self):
+        """
+        Symbol constructor -- not intended to be called directly by Kconfiglib
+        clients.
+        """
+        # These attributes are always set on the instance from outside and
+        # don't need defaults:
+        #   kconfig
+        #   direct_dep
+        #   is_constant
+        #   name
+        #   rev_dep
+        #   weak_rev_dep
+
+        self.orig_type = UNKNOWN
+        self.defaults = []
+        self.selects = []
+        self.implies = []
+        self.ranges = []
+
+        self.nodes = []
+
+        self.user_value = \
+        self.choice = \
+        self.env_var = \
+        self._cached_str_val = self._cached_tri_val = self._cached_vis = \
+        self._cached_assignable = None
+
+        # _write_to_conf is calculated along with the value. If True, the
+        # Symbol gets a .config entry.
+
+        self.is_allnoconfig_y = \
+        self._was_set = \
+        self._write_to_conf = False
+
+        # See Kconfig._build_dep()
+        self._dependents = set()
+
+    def _get_assignable(self):
+        """
+        Worker function for the 'assignable' attribute.
+        """
+        if self.orig_type not in (BOOL, TRISTATE):
+            return ()
+
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        vis = self.visibility
+
+        if not vis:
+            return ()
+
+        rev_dep_val = expr_value(self.rev_dep)
+
+        if vis == 2:
+            if self.choice:
+                return (2,)
+
+            if not rev_dep_val:
+                if self.type == BOOL or expr_value(self.weak_rev_dep) == 2:
+                    return (0, 2)
+                return (0, 1, 2)
+
+            if rev_dep_val == 2:
+                return (2,)
+
+            # rev_dep_val == 1
+
+            if self.type == BOOL or expr_value(self.weak_rev_dep) == 2:
+                return (2,)
+            return (1, 2)
+
+        # vis == 1
+
+        # Must be a tristate here, because bool m visibility gets promoted to y
+
+        if not rev_dep_val:
+            return (0, 1) if expr_value(self.weak_rev_dep) != 2 else (0, 2)
+
+        if rev_dep_val == 2:
+            return (2,)
+
+        # vis == rev_dep_val == 1
+
+        return (1,)
+
+    def _is_user_assignable(self):
+        """
+        Returns True if the symbol has a prompt, meaning a user value might
+        have an effect on it. Used as an optimization to skip invalidation when
+        promptless symbols are assigned to (given a user value).
+
+        Prints a warning if the symbol has no prompt. In some contexts (e.g.
+        when loading a .config files) assignments to promptless symbols are
+        normal and expected, so the warning can be disabled.
+        """
+        for node in self.nodes:
+            if node.prompt:
+                return True
+
+        if self.kconfig._warn_no_prompt:
+            self.kconfig._warn(self.name + " has no prompt, meaning user "
+                               "values have no effect on it")
+        return False
+
+    def _invalidate(self):
+        """
+        Marks the symbol as needing to be recalculated.
+        """
+        self._cached_str_val = self._cached_tri_val = self._cached_vis = \
+            self._cached_assignable = None
+
+    def _rec_invalidate(self):
+        """
+        Invalidates the symbol and all items that (possibly) depend on it.
+        """
+        if self is self.kconfig.modules:
+            # Invalidating MODULES has wide-ranging effects
+            self.kconfig._invalidate_all()
+        else:
+            self._invalidate()
+
+            for item in self._dependents:
+                # _cached_vis doubles as a flag that tells us whether 'item'
+                # has cached values, because it's calculated as a side effect
+                # of calculating all other (non-constant) cached values.
+                #
+                # If item._cached_vis is None, it means there can't be cached
+                # values on other items that depend on 'item', because if there
+                # were, some value on 'item' would have been calculated and
+                # item._cached_vis set as a side effect. It's therefore safe to
+                # stop the invalidation at symbols with _cached_vis None.
+                #
+                # This approach massively speeds up scripts that set a lot of
+                # values, vs simply invalidating all possibly dependent symbols
+                # (even when you already have a list of all the dependent
+                # symbols, because some symbols get huge dependency trees).
+                #
+                # This gracefully handles dependency loops too, which is nice
+                # for choices, where the choice depends on the choice symbols
+                # and vice versa.
+                if item._cached_vis is not None:
+                    item._rec_invalidate()
+
+class Choice(object):
+    """
+    Represents a choice statement:
+
+      choice
+          ...
+      endchoice
+
+    The following attributes are available on Choice instances. They should be
+    treated as read-only, and some are implemented through @property magic (but
+    are still efficient to access due to internal caching).
+
+    Note: Prompts, help texts, and locations are stored in the Choice's
+    MenuNode(s) rather than in the Choice itself. Check the MenuNode class and
+    the Choice.nodes attribute. This organization matches the C tools.
+
+    name:
+      The name of the choice, e.g. "FOO" for 'choice FOO', or None if the
+      Choice has no name. I can't remember ever seeing named choices in
+      practice, but the C tools support them too.
+
+    type:
+      The type of the choice. One of BOOL, TRISTATE, UNKNOWN. UNKNOWN is for
+      choices defined without a type where none of the contained symbols have a
+      type either (otherwise the choice inherits the type of the first symbol
+      defined with a type).
+
+      When running without modules (CONFIG_MODULES=n), TRISTATE choices
+      magically change type to BOOL. This matches the C tools, and makes sense
+      for menuconfig-like functionality.
+
+    orig_type:
+      The type as given in the Kconfig file, without any magic applied. Used
+      when printing the choice.
+
+    tri_value:
+      The tristate value (mode) of the choice. A choice can be in one of three
+      modes:
+
+        0 (n) - The choice is disabled and no symbols can be selected. For
+                visible choices, this mode is only possible for choices with
+                the 'optional' flag set (see kconfig-language.txt).
+
+        1 (m) - Any number of choice symbols can be set to m, the rest will
+                be n.
+
+        2 (y) - One symbol will be y, the rest n.
+
+      Only tristate choices can be in m mode. The visibility of the choice is
+      an upper bound on the mode, and the mode in turn is an upper bound on the
+      visibility of the choice symbols.
+
+      To change the mode, use Choice.set_value().
+
+      Implementation note:
+        The C tools internally represent choices as a type of symbol, with
+        special-casing in many code paths. This is why there is a lot of
+        similarity to Symbol. The value (mode) of a choice is really just a
+        normal symbol value, and an implicit reverse dependency forces its
+        lower bound to m for visible non-optional choices (the reverse
+        dependency is 'm && <visibility>').
+
+        Symbols within choices get the choice propagated as a dependency to
+        their properties. This turns the mode of the choice into an upper bound
+        on e.g. the visibility of choice symbols, and explains the gotcha
+        related to printing choice symbols mentioned in the module docstring.
+
+        Kconfiglib uses a separate Choice class only because it makes the code
+        and interface less confusing (especially in a user-facing interface).
+        Corresponding attributes have the same name in the Symbol and Choice
+        classes, for consistency and compatibility.
+
+    assignable:
+      See the symbol class documentation. Gives the assignable values (modes).
+
+    visibility:
+      See the Symbol class documentation. Acts on the value (mode).
+
+    selection:
+      The Symbol instance of the currently selected symbol. None if the Choice
+      is not in y mode or has no selected symbol (due to unsatisfied
+      dependencies on choice symbols).
+
+      WARNING: Do not assign directly to this. It will break things. Call
+      sym.set_value(2) on the choice symbol you want to select instead.
+
+    user_value:
+      The value (mode) selected by the user through Choice.set_value(). Either
+      0, 1, or 2, or None if the user hasn't selected a mode. See
+      Symbol.user_value.
+
+      WARNING: Do not assign directly to this. It will break things. Use
+      Choice.set_value() instead.
+
+    user_selection:
+      The symbol selected by the user (by setting it to y). Ignored if the
+      choice is not in y mode, but still remembered so that the choice "snaps
+      back" to the user selection if the mode is changed back to y. This might
+      differ from 'selection' due to unsatisfied dependencies.
+
+      WARNING: Do not assign directly to this. It will break things. Call
+      sym.set_value(2) on the choice symbol to be selected instead.
+
+    syms:
+      List of symbols contained in the choice.
+
+      Gotcha: If a symbol depends on the previous symbol within a choice so
+      that an implicit menu is created, it won't be a choice symbol, and won't
+      be included in 'syms'. There are real-world examples of this, and it was
+      a PITA to support in older versions of Kconfiglib that didn't implement
+      the menu structure.
+
+    nodes:
+      A list of MenuNodes for this choice. In practice, the list will probably
+      always contain a single MenuNode, but it is possible to give a choice a
+      name and define it in multiple locations (i've never even seen a named
+      choice though).
+
+    defaults:
+      List of (symbol, cond) tuples for the choice's 'defaults' properties. For
+      example, 'default A if B && C' is represented as (A, (AND, B, C)). If
+      there is no condition, 'cond' is self.config.y.
+
+      Note that 'depends on' and parent dependencies are propagated to
+      'default' conditions.
+
+    is_optional:
+      True if the choice has the 'optional' flag set on it and can be in
+      n mode.
+
+    kconfig:
+      The Kconfig instance this choice is from.
+    """
+    __slots__ = (
+        "_cached_assignable",
+        "_cached_selection",
+        "_cached_vis",
+        "_dependents",
+        "_was_set",
+        "defaults",
+        "is_constant",
+        "is_optional",
+        "kconfig",
+        "name",
+        "nodes",
+        "orig_type",
+        "syms",
+        "user_selection",
+        "user_value",
+    )
+
+    #
+    # Public interface
+    #
+
+    @property
+    def type(self):
+        """
+        Returns the type of the choice. See Symbol.type.
+        """
+        if self.orig_type == TRISTATE and not self.kconfig.modules.tri_value:
+            return BOOL
+
+        return self.orig_type
+
+    @property
+    def str_value(self):
+        """
+        See the class documentation.
+        """
+        return TRI_TO_STR[self.tri_value]
+
+    @property
+    def tri_value(self):
+        """
+        See the class documentation.
+        """
+        # This emulates a reverse dependency of 'm && visibility' for
+        # non-optional choices, which is how the C implementation does it
+
+        val = 0 if self.is_optional else 1
+
+        if self.user_value is not None:
+            val = max(val, self.user_value)
+
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        val = min(val, self.visibility)
+
+        # Promote m to y for boolean choices
+        return 2 if val == 1 and self.type == BOOL else val
+
+    @property
+    def assignable(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_assignable is not None:
+            return self._cached_assignable
+
+        self._cached_assignable = self._get_assignable()
+        return self._cached_assignable
+
+    @property
+    def visibility(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_vis is not None:
+            return self._cached_vis
+
+        self._cached_vis = _get_visibility(self)
+        return self._cached_vis
+
+    @property
+    def selection(self):
+        """
+        See the class documentation.
+        """
+        if self._cached_selection is not _NO_CACHED_SELECTION:
+            return self._cached_selection
+
+        self._cached_selection = self._get_selection()
+        return self._cached_selection
+
+    def set_value(self, value):
+        """
+        Sets the user value (mode) of the choice. Like for Symbol.set_value(),
+        the visibility might truncate the value. Choices without the 'optional'
+        attribute (is_optional) can never be in n mode, but 0 is still accepted
+        since it's not a malformed value (though it will have no effect).
+
+        Returns True if the value is valid for the type of the choice, and
+        False otherwise. This only looks at the form of the value. Check the
+        Choice.assignable attribute to see what values are currently in range
+        and would actually be reflected in the mode of the choice.
+        """
+        if value == self.user_value:
+            # We know the value must be valid if it was successfully set
+            # previously
+            self._was_set = True
+            return True
+
+        if not ((self.orig_type == BOOL     and value in (0, 2)    ) or
+                (self.orig_type == TRISTATE and value in (0, 1, 2))):
+            self.kconfig._warn("the value '{}' is invalid for the choice, "
+                               "which has type {}. Assignment ignored"
+                               .format(value, TYPE_TO_STR[self.orig_type]))
+            return False
+
+        self.user_value = value
+        self._was_set = True
+        self._rec_invalidate()
+
+        return True
+
+    def unset_value(self):
+        """
+        Resets the user value (mode) and user selection of the Choice, as if
+        the user had never touched the mode or any of the choice symbols.
+        """
+        if self.user_value is not None or self.user_selection:
+            self.user_value = self.user_selection = None
+            self._rec_invalidate()
+
+    def __repr__(self):
+        """
+        Returns a string with information about the choice when it is evaluated
+        on e.g. the interactive Python prompt.
+        """
+        fields = []
+
+        fields.append("choice" if self.name is None else \
+                      "choice " + self.name)
+        fields.append(TYPE_TO_STR[self.type])
+
+        for node in self.nodes:
+            if node.prompt:
+                fields.append('"{}"'.format(node.prompt[0]))
+
+        fields.append("mode " + self.str_value)
+
+        if self.user_value is not None:
+            fields.append('user mode {}'.format(TRI_TO_STR[self.user_value]))
+
+        if self.selection:
+            fields.append("{} selected".format(self.selection.name))
+
+        if self.user_selection:
+            user_sel_str = "{} selected by user" \
+                           .format(self.user_selection.name)
+
+            if self.selection is not self.user_selection:
+                user_sel_str += " (overridden)"
+
+            fields.append(user_sel_str)
+
+        fields.append("visibility " + TRI_TO_STR[self.visibility])
+
+        if self.is_optional:
+            fields.append("optional")
+
+        for node in self.nodes:
+            fields.append("{}:{}".format(node.filename, node.linenr))
+
+        return "<{}>".format(", ".join(fields))
+
+    def __str__(self):
+        """
+        Returns a string representation of the choice when it is printed,
+        matching the Kconfig format (though without the contained choice
+        symbols). Prompts and help texts are included, though they really
+        belong to the choice's menu nodes rather than the choice itself.
+
+        See Symbol.__str__() as well.
+        """
+        return _sym_choice_str(self)
+
+    #
+    # Private methods
+    #
+
+    def __init__(self):
+        """
+        Choice constructor -- not intended to be called directly by Kconfiglib
+        clients.
+        """
+        # These attributes are always set on the instance from outside and
+        # don't need defaults:
+        #   kconfig
+
+        self.orig_type = UNKNOWN
+        self.syms = []
+        self.defaults = []
+
+        self.nodes = []
+
+        self.name = \
+        self.user_value = self.user_selection = \
+        self._cached_vis = self._cached_assignable = None
+
+        self._cached_selection = _NO_CACHED_SELECTION
+
+        # is_constant is checked by _make_depend_on(). Just set it to avoid
+        # having to special-case choices.
+        self.is_constant = self.is_optional = False
+
+        # See Kconfig._build_dep()
+        self._dependents = set()
+
+    def _get_assignable(self):
+        """
+        Worker function for the 'assignable' attribute.
+        """
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        vis = self.visibility
+
+        if not vis:
+            return ()
+
+        if vis == 2:
+            if not self.is_optional:
+                return (2,) if self.type == BOOL else (1, 2)
+            return (0, 2) if self.type == BOOL else (0, 1, 2)
+
+        # vis == 1
+
+        return (0, 1) if self.is_optional else (1,)
+
+    def _get_selection(self):
+        """
+        Worker function for the 'selection' attribute.
+        """
+        # Warning: See Symbol._rec_invalidate(), and note that this is a hidden
+        # function call (property magic)
+        if self.tri_value != 2:
+            return None
+
+        # Use the user selection if it's visible
+        if self.user_selection and self.user_selection.visibility == 2:
+            return self.user_selection
+
+        # Otherwise, check if we have a default
+        for sym, cond in self.defaults:
+            # The default symbol must be visible too
+            if expr_value(cond) and sym.visibility:
+                return sym
+
+        # Otherwise, pick the first visible symbol, if any
+        for sym in self.syms:
+            if sym.visibility:
+                return sym
+
+        # Couldn't find a selection
+        return None
+
+    def _invalidate(self):
+        self._cached_vis = self._cached_assignable = None
+        self._cached_selection = _NO_CACHED_SELECTION
+
+    def _rec_invalidate(self):
+        """
+        See Symbol._rec_invalidate()
+        """
+        self._invalidate()
+
+        for item in self._dependents:
+            if item._cached_vis is not None:
+                item._rec_invalidate()
+
+class MenuNode(object):
+    """
+    Represents a menu node in the configuration. This corresponds to an entry
+    in e.g. the 'make menuconfig' interface, though non-visible choices, menus,
+    and comments also get menu nodes. If a symbol or choice is defined in
+    multiple locations, it gets one menu node for each location.
+
+    The top-level menu node, corresponding to the implicit top-level menu, is
+    available in Kconfig.top_node.
+
+    The menu nodes for a Symbol or Choice can be found in the
+    Symbol/Choice.nodes attribute. Menus and comments are represented as plain
+    menu nodes, with their text stored in the prompt attribute (prompt[0]).
+    This mirrors the C implementation.
+
+    The following attributes are available on MenuNode instances. They should
+    be viewed as read-only.
+
+    item:
+      Either a Symbol, a Choice, or one of the constants MENU and COMMENT.
+      Menus and comments are represented as plain menu nodes. Ifs are collapsed
+      (matching the C implementation) and do not appear in the final menu tree.
+
+    next:
+      The following menu node. None if there is no following node.
+
+    list:
+      The first child menu node. None if there are no children.
+
+      Choices and menus naturally have children, but Symbols can also have
+      children because of menus created automatically from dependencies (see
+      kconfig-language.txt).
+
+    parent:
+      The parent menu node. None if there is no parent.
+
+    prompt:
+      A (string, cond) tuple with the prompt for the menu node and its
+      conditional expression (which is self.kconfig.y if there is no
+      condition). None if there is no prompt.
+
+      For symbols and choices, the prompt is stored in the MenuNode rather than
+      the Symbol or Choice instance. For menus and comments, the prompt holds
+      the text.
+
+    help:
+      The help text for the menu node for Symbols and Choices. None if there is
+      no help text. Always stored in the node rather than the Symbol or Choice.
+      It is possible to have a separate help text at each location if a symbol
+      is defined in multiple locations.
+
+    dep:
+      The 'depends on' dependencies for the menu node, or self.kconfig.y if
+      there are no dependencies. Parent dependencies are propagated to this
+      attribute, and this attribute is then in turn propagated to the
+      properties of symbols and choices.
+
+      If a symbol is defined in multiple locations, only the properties defined
+      at a particular location get the corresponding MenuNode.dep dependencies
+      propagated to them.
+
+    visibility:
+      The 'visible if' dependencies for the menu node (which must represent a
+      menu), or self.kconfig.y if there are no 'visible if' dependencies.
+      'visible if' dependencies are recursively propagated to the prompts of
+      symbols and choices within the menu.
+
+    is_menuconfig:
+      True if the symbol for the menu node (it must be a symbol) was defined
+      with 'menuconfig' rather than 'config' (at this location). This is a hint
+      on how to display the menu entry (display the children in a separate menu
+      rather than indenting them). It's ignored internally by Kconfiglib,
+      except when printing symbols.
+
+    filename/linenr:
+      The location where the menu node appears.
+
+    kconfig:
+      The Kconfig instance the menu node is from.
+    """
+    __slots__ = (
+        "dep",
+        "filename",
+        "help",
+        "is_menuconfig",
+        "item",
+        "kconfig",
+        "linenr",
+        "list",
+        "next",
+        "parent",
+        "prompt",
+        "visibility",
+    )
+
+    def __repr__(self):
+        """
+        Returns a string with information about the menu node when it is
+        evaluated on e.g. the interactive Python prompt.
+        """
+        fields = []
+
+        if isinstance(self.item, Symbol):
+            fields.append("menu node for symbol " + self.item.name)
+
+        elif isinstance(self.item, Choice):
+            s = "menu node for choice"
+            if self.item.name is not None:
+                s += " " + self.item.name
+            fields.append(s)
+
+        elif self.item == MENU:
+            fields.append("menu node for menu")
+
+        elif self.item == COMMENT:
+            fields.append("menu node for comment")
+
+        elif self.item is None:
+            fields.append("menu node for if (should not appear in the final "
+                          " tree)")
+
+        else:
+            raise InternalError("unable to determine type in "
+                                "MenuNode.__repr__()")
+
+        if self.prompt:
+            fields.append('prompt "{}" (visibility {})'
+                          .format(self.prompt[0],
+                                  TRI_TO_STR[expr_value(self.prompt[1])]))
+
+        if isinstance(self.item, Symbol) and self.is_menuconfig:
+            fields.append("is menuconfig")
+
+        fields.append("deps " + TRI_TO_STR[expr_value(self.dep)])
+
+        if self.item == MENU:
+            fields.append("'visible if' deps " + \
+                          TRI_TO_STR[expr_value(self.visibility)])
+
+        if isinstance(self.item, (Symbol, Choice)) and self.help is not None:
+            fields.append("has help")
+
+        if self.list:
+            fields.append("has child")
+
+        if self.next:
+            fields.append("has next")
+
+        fields.append("{}:{}".format(self.filename, self.linenr))
+
+        return "<{}>".format(", ".join(fields))
+
+    def __str__(self):
+        """
+        Returns a string representation of the MenuNode, matching the Kconfig
+        format.
+
+        For Symbol and Choice menu nodes, this function simply calls through to
+        MenuNode.item.__str__(). For MENU and COMMENT nodes, a Kconfig-like
+        representation of the menu or comment is returned.
+        """
+        if isinstance(self.item, (Symbol, Choice)):
+            return self.item.__str__()
+
+        if self.item in (MENU, COMMENT):
+            s = ("menu" if self.item == MENU else "comment") + \
+                ' "{}"\n'.format(escape(self.prompt[0]))
+
+            if self.dep is not self.kconfig.y:
+                s += "\tdepends on {}\n".format(expr_str(self.dep))
+
+            if self.item == MENU and self.visibility is not self.kconfig.y:
+                s += "\tvisible if {}\n".format(expr_str(self.visibility))
+
+            return s
+
+        # 'if' node. Should never appear in the final tree.
+        return "if " + expr_str(self.dep)
+
+class KconfigSyntaxError(Exception):
+    """
+    Exception raised for syntax errors.
+    """
+    pass
+
+class InternalError(Exception):
+    """
+    Exception raised for internal errors.
+    """
+    pass
+
+#
+# Public functions
+#
+
+def expr_value(expr):
+    """
+    Evaluates the expression 'expr' to a tristate value. Returns 0 (n), 1 (m),
+    or 2 (y).
+
+    'expr' must be an already-parsed expression from a Symbol, Choice, or
+    MenuNode property. To evaluate an expression represented as a string, use
+    Kconfig.eval_string().
+
+    Passing subexpressions of expressions to this function works as expected.
+    """
+    if not isinstance(expr, tuple):
+        return expr.tri_value
+
+    if expr[0] == AND:
+        v1 = expr_value(expr[1])
+        # Short-circuit the n case as an optimization (~5% faster
+        # allnoconfig.py and allyesconfig.py, as of writing)
+        return 0 if not v1 else min(v1, expr_value(expr[2]))
+
+    if expr[0] == OR:
+        v1 = expr_value(expr[1])
+        # Short-circuit the y case as an optimization
+        return 2 if v1 == 2 else max(v1, expr_value(expr[2]))
+
+    if expr[0] == NOT:
+        return 2 - expr_value(expr[1])
+
+    if expr[0] in _RELATIONS:
+        # Implements <, <=, >, >= comparisons as well. These were added to
+        # kconfig in 31847b67 (kconfig: allow use of relations other than
+        # (in)equality).
+
+        # This mirrors the C tools pretty closely. Perhaps there's a more
+        # pythonic way to structure this.
+
+        oper, op1, op2 = expr
+
+        # If both operands are strings...
+        if op1.orig_type == STRING and op2.orig_type == STRING:
+            # ...then compare them lexicographically
+            comp = _strcmp(op1.str_value, op2.str_value)
+        else:
+            # Otherwise, try to compare them as numbers...
+            try:
+                comp = int(op1.str_value, _TYPE_TO_BASE[op1.orig_type]) - \
+                       int(op2.str_value, _TYPE_TO_BASE[op2.orig_type])
+            except ValueError:
+                # Fall back on a lexicographic comparison if the operands don't
+                # parse as numbers
+                comp = _strcmp(op1.str_value, op2.str_value)
+
+        if   oper == EQUAL:         res = comp == 0
+        elif oper == UNEQUAL:       res = comp != 0
+        elif oper == LESS:          res = comp < 0
+        elif oper == LESS_EQUAL:    res = comp <= 0
+        elif oper == GREATER:       res = comp > 0
+        elif oper == GREATER_EQUAL: res = comp >= 0
+
+        return 2*res
+
+    _internal_error("Internal error while evaluating expression: "
+                    "unknown operation {}.".format(expr[0]))
+
+def expr_str(expr):
+    """
+    Returns the string representation of the expression 'expr', as in a Kconfig
+    file.
+
+    Passing subexpressions of expressions to this function works as expected.
+    """
+    if not isinstance(expr, tuple):
+        if isinstance(expr, Choice):
+            if expr.name is not None:
+                return "<choice {}>".format(expr.name)
+            return "<choice>"
+
+        # Symbol
+
+        if expr.is_constant:
+            return '"{}"'.format(escape(expr.name))
+
+        return expr.name
+
+    if expr[0] == NOT:
+        if isinstance(expr[1], Symbol):
+            return "!" + expr_str(expr[1])
+        return "!({})".format(expr_str(expr[1]))
+
+    if expr[0] == AND:
+        return "{} && {}".format(_format_and_op(expr[1]),
+                                 _format_and_op(expr[2]))
+
+    if expr[0] == OR:
+        return "{} || {}".format(expr_str(expr[1]), expr_str(expr[2]))
+
+    # Relation
+    return "{} {} {}".format(expr_str(expr[1]),
+                             _REL_TO_STR[expr[0]],
+                             expr_str(expr[2]))
+
+# escape()/unescape() helpers
+_escape_re_sub = re.compile(r'(["\\])').sub
+_unescape_re_sub = re.compile(r"\\(.)").sub
+
+def escape(s):
+    r"""
+    Escapes the string 's' in the same fashion as is done for display in
+    Kconfig format and when writing strings to a .config file. " and \ are
+    replaced by \" and \\, respectively.
+    """
+    return _escape_re_sub(r"\\\1", s)
+
+def unescape(s):
+    r"""
+    Unescapes the string 's'. \ followed by any character is replaced with just
+    that character. Used internally when reading .config files.
+    """
+    return _unescape_re_sub(r"\1", s)
+
+#
+# Internal functions
+#
+
+def _get_visibility(sc):
+    """
+    Symbols and Choices have a "visibility" that acts as an upper bound on the
+    values a user can set for them, corresponding to the visibility in e.g.
+    'make menuconfig'. This function calculates the visibility for the Symbol
+    or Choice 'sc' -- the logic is nearly identical.
+    """
+    vis = 0
+
+    for node in sc.nodes:
+        if node.prompt:
+            vis = max(vis, expr_value(node.prompt[1]))
+
+    if isinstance(sc, Symbol) and sc.choice:
+        if sc.choice.orig_type == TRISTATE and sc.orig_type != TRISTATE and \
+           sc.choice.tri_value != 2:
+            # Non-tristate choice symbols are only visible in y mode
+            return 0
+
+        if sc.orig_type == TRISTATE and vis == 1 and sc.choice.tri_value == 2:
+            # Choice symbols with m visibility are not visible in y mode
+            return 0
+
+    # Promote m to y if we're dealing with a non-tristate (possibly due to
+    # modules being disabled)
+    if vis == 1 and sc.type != TRISTATE:
+        return 2
+
+    return vis
+
+def _make_depend_on(sym, expr):
+    """
+    Adds 'sym' as a dependency to all symbols in 'expr'. Constant symbols in
+    'expr' are skipped as they can never change value anyway.
+    """
+    if not isinstance(expr, tuple):
+        if not expr.is_constant:
+            expr._dependents.add(sym)
+
+    elif expr[0] in (AND, OR):
+        _make_depend_on(sym, expr[1])
+        _make_depend_on(sym, expr[2])
+
+    elif expr[0] == NOT:
+        _make_depend_on(sym, expr[1])
+
+    elif expr[0] in _RELATIONS:
+        if not expr[1].is_constant:
+            expr[1]._dependents.add(sym)
+        if not expr[2].is_constant:
+            expr[2]._dependents.add(sym)
+
+    else:
+        _internal_error("Internal error while fetching symbols from an "
+                        "expression with token stream {}.".format(expr))
+
+def _format_and_op(expr):
+    """
+    expr_str() helper. Returns the string representation of 'expr', which is
+    assumed to be an operand to AND, with parentheses added if needed.
+    """
+    if isinstance(expr, tuple) and expr[0] == OR:
+        return "({})".format(expr_str(expr))
+    return expr_str(expr)
+
+def _indentation(line):
+    """
+    Returns the length of the line's leading whitespace, treating tab stops as
+    being spaced 8 characters apart.
+    """
+    line = line.expandtabs()
+    return len(line) - len(line.lstrip())
+
+def _deindent(line, indent):
+    """
+    Deindents 'line' by 'indent' spaces.
+    """
+    line = line.expandtabs()
+    if len(line) <= indent:
+        return line
+    return line[indent:]
+
+def _is_base_n(s, n):
+    try:
+        int(s, n)
+        return True
+    except ValueError:
+        return False
+
+def _strcmp(s1, s2):
+    """
+    strcmp()-alike that returns -1, 0, or 1.
+    """
+    return (s1 > s2) - (s1 < s2)
+
+def _stderr_msg(msg, filename, linenr):
+    if filename is not None:
+        msg = "{}:{}: {}".format(filename, linenr, msg)
+
+    sys.stderr.write(msg + "\n")
+
+def _internal_error(msg):
+    raise InternalError(
+        msg +
+        "\nSorry! You may want to send an email to ulfalizer a.t Google's "
+        "email service to tell me about this. Include the message above and "
+        "the stack trace and describe what you were doing.")
+
+# Printing functions
+
+def _sym_choice_str(sc):
+    """
+    Symbol/choice __str__() implementation. These have many properties in
+    common, so it makes sense to handle them together.
+    """
+    lines = []
+
+    def indent_add(s):
+        lines.append("\t" + s)
+
+    # We print the prompt(s) and help text(s) too as a convenience, even though
+    # they're actually part of the MenuNode. If a symbol or choice is defined
+    # in multiple locations (has more than one MenuNode), we output one
+    # statement for each location, and print all the properties that belong to
+    # the symbol/choice itself only at the first location. This gives output
+    # that would function if fed to a Kconfig parser, even for such
+    # symbols/choices (choices defined in multiple locations gets a bit iffy
+    # since they also have child nodes, though I've never seen such a choice).
+
+    if not sc.nodes:
+        return ""
+
+    for node in sc.nodes:
+        if isinstance(sc, Symbol):
+            if node.is_menuconfig:
+                lines.append("menuconfig " + sc.name)
+            else:
+                lines.append("config " + sc.name)
+        else:
+            if sc.name is None:
+                lines.append("choice")
+            else:
+                lines.append("choice " + sc.name)
+
+        if node is sc.nodes[0] and sc.orig_type != UNKNOWN:
+            indent_add(TYPE_TO_STR[sc.orig_type])
+
+        if node.prompt:
+            prompt, cond = node.prompt
+            prompt_str = 'prompt "{}"'.format(escape(prompt))
+            if cond is not sc.kconfig.y:
+                prompt_str += " if " + expr_str(cond)
+            indent_add(prompt_str)
+
+        if node is sc.nodes[0]:
+            if isinstance(sc, Symbol):
+                if sc.is_allnoconfig_y:
+                    indent_add("option allnoconfig_y")
+
+                if sc is sc.kconfig.defconfig_list:
+                    indent_add("option defconfig_list")
+
+                if sc.env_var is not None:
+                    indent_add('option env="{}"'.format(sc.env_var))
+
+                if sc is sc.kconfig.modules:
+                    indent_add("option modules")
+
+            if isinstance(sc, Symbol):
+                for low, high, cond in sc.ranges:
+                    range_string = "range {} {}" \
+                                   .format(expr_str(low), expr_str(high))
+                    if cond is not sc.kconfig.y:
+                        range_string += " if " + expr_str(cond)
+                    indent_add(range_string)
+
+            for default, cond in sc.defaults:
+                default_string = "default " + expr_str(default)
+                if cond is not sc.kconfig.y:
+                    default_string += " if " + expr_str(cond)
+                indent_add(default_string)
+
+            if isinstance(sc, Choice) and sc.is_optional:
+                indent_add("optional")
+
+            if isinstance(sc, Symbol):
+                for select, cond in sc.selects:
+                    select_string = "select " + select.name
+                    if cond is not sc.kconfig.y:
+                        select_string += " if " + expr_str(cond)
+                    indent_add(select_string)
+
+                for imply, cond in sc.implies:
+                    imply_string = "imply " + imply.name
+                    if cond is not sc.kconfig.y:
+                        imply_string += " if " + expr_str(cond)
+                    indent_add(imply_string)
+
+        if node.help is not None:
+            indent_add("help")
+            for line in node.help.splitlines():
+                indent_add("  " + line)
+
+        # Add a blank line if there are more nodes to print
+        if node is not sc.nodes[-1]:
+            lines.append("")
+
+    return "\n".join(lines) + "\n"
+
+# Menu manipulation
+
+def _expr_depends_on(expr, sym):
+    """
+    Reimplementation of expr_depends_symbol() from mconf.c. Used to
+    determine if a submenu should be implicitly created. This also influences
+    which items inside choice statements are considered choice items.
+    """
+    if not isinstance(expr, tuple):
+        return expr is sym
+
+    if expr[0] in (EQUAL, UNEQUAL):
+        # Check for one of the following:
+        # sym = m/y, m/y = sym, sym != n, n != sym
+
+        left, right = expr[1:]
+
+        if right is sym:
+            left, right = right, left
+
+        if left is not sym:
+            return False
+
+        return (expr[0] == EQUAL and right is sym.kconfig.m or \
+                                     right is sym.kconfig.y) or \
+               (expr[0] == UNEQUAL and right is sym.kconfig.n)
+
+    if expr[0] == AND:
+        return _expr_depends_on(expr[1], sym) or \
+               _expr_depends_on(expr[2], sym)
+
+    return False
+
+def _has_auto_menu_dep(node1, node2):
+    """
+    Returns True if node2 has an "automatic menu dependency" on node1. If node2
+    has a prompt, we check its condition. Otherwise, we look directly at
+    node2.dep.
+    """
+    if node2.prompt:
+        return _expr_depends_on(node2.prompt[1], node1.item)
+
+    # If we have no prompt, use the menu node dependencies instead
+    return _expr_depends_on(node2.dep, node1.item)
+
+def _check_auto_menu(node):
+    """
+    Looks for menu nodes after 'node' that depend on it. Creates an implicit
+    menu rooted at 'node' with the nodes as the children if such nodes are
+    found. The recursive call to _finalize_tree() makes this work recursively.
+    """
+    cur = node
+    while cur.next and _has_auto_menu_dep(node, cur.next):
+        _finalize_tree(cur.next)
+        cur = cur.next
+        cur.parent = node
+
+    if cur is not node:
+        node.list = node.next
+        node.next = cur.next
+        cur.next = None
+
+def _flatten(node):
+    """
+    "Flattens" menu nodes without prompts (e.g. 'if' nodes and non-visible
+    symbols with children from automatic menu creation) so that their children
+    appear after them instead. This gives a clean menu structure with no
+    unexpected "jumps" in the indentation.
+    """
+    while node:
+        if node.list and (not node.prompt or node.prompt[0] == ""):
+
+            last_node = node.list
+            while 1:
+                last_node.parent = node.parent
+                if not last_node.next:
+                    break
+                last_node = last_node.next
+
+            last_node.next = node.next
+            node.next = node.list
+            node.list = None
+
+        node = node.next
+
+def _remove_ifs(node):
+    """
+    Removes 'if' nodes (which can be recognized by MenuNode.item being None),
+    which are assumed to already have been flattened. The C implementation
+    doesn't bother to do this, but we expose the menu tree directly, and it
+    makes it nicer to work with.
+    """
+    first = node.list
+    while first and first.item is None:
+        first = first.next
+
+    cur = first
+    while cur:
+        if cur.next and cur.next.item is None:
+            cur.next = cur.next.next
+        cur = cur.next
+
+    node.list = first
+
+def _finalize_choice(node):
+    """
+    Finalizes a choice, marking each symbol whose menu node has the choice as
+    the parent as a choice symbol, and automatically determining types if not
+    specified.
+    """
+    choice = node.item
+
+    cur = node.list
+    while cur:
+        if isinstance(cur.item, Symbol):
+            cur.item.choice = choice
+            choice.syms.append(cur.item)
+        cur = cur.next
+
+    # If no type is specified for the choice, its type is that of
+    # the first choice item with a specified type
+    if choice.orig_type == UNKNOWN:
+        for item in choice.syms:
+            if item.orig_type != UNKNOWN:
+                choice.orig_type = item.orig_type
+                break
+
+    # Each choice item of UNKNOWN type gets the type of the choice
+    for sym in choice.syms:
+        if sym.orig_type == UNKNOWN:
+            sym.orig_type = choice.orig_type
+
+def _finalize_tree(node):
+    """
+    Creates implicit menus from dependencies (see kconfig-language.txt),
+    removes 'if' nodes, and finalizes choices. This pretty closely mirrors
+    menu_finalize() from the C implementation, though we propagate dependencies
+    during parsing instead.
+    """
+    # The ordering here gets a bit tricky. It's important to do things in this
+    # order to have everything work out correctly.
+
+    if node.list:
+        # The menu node has children. Finalize them.
+        cur = node.list
+        while cur:
+            _finalize_tree(cur)
+            # Note: _finalize_tree() might have changed cur.next. This is
+            # expected, so that we jump over e.g. implicitly created submenus.
+            cur = cur.next
+
+    elif node.item is not None:
+        # The menu node has no children (yet). See if we can create an implicit
+        # menu rooted at it (due to menu nodes after it depending on it).
+        _check_auto_menu(node)
+
+    if node.list:
+        # We have a node with finalized children. Do final steps to finalize
+        # this node.
+        _flatten(node.list)
+        _remove_ifs(node)
+
+    # Empty choices (node.list None) are possible, so this needs to go outside
+    if isinstance(node.item, Choice):
+        _finalize_choice(node)
+
+def _wordexp_expand(value):
+    """
+    Return a list of expanded tokens, using roughly the same algorithm
+    as wordexp(3)
+    """
+    ifs = os.environ.get("IFS", " \t\n")
+    value = os.path.expandvars(value).strip(ifs)
+    if len(ifs) > 0:
+        for i in ifs[1:]:  # collapse all IFS delimiters
+            value = value.replace(i, ifs[0])
+        return value.split(ifs[0])
+    else:
+        return [value]
+
+#
+# Public global constants
+#
+
+# Integers representing symbol types
+(
+    BOOL,
+    HEX,
+    INT,
+    STRING,
+    TRISTATE,
+    UNKNOWN
+) = range(6)
+
+# Integers representing expression types
+(
+    AND,
+    OR,
+    NOT,
+    EQUAL,
+    UNEQUAL,
+    LESS,
+    LESS_EQUAL,
+    GREATER,
+    GREATER_EQUAL,
+) = range(9)
+
+# Integers representing menu and comment menu nodes
+(
+    MENU,
+    COMMENT,
+) = range(2)
+
+# Converts a symbol/choice type to a string
+TYPE_TO_STR = {
+    UNKNOWN:  "unknown",
+    BOOL:     "bool",
+    TRISTATE: "tristate",
+    STRING:   "string",
+    HEX:      "hex",
+    INT:      "int",
+}
+
+TRI_TO_STR = {
+    0: "n",
+    1: "m",
+    2: "y",
+}
+
+STR_TO_TRI = {
+    "n": 0,
+    "m": 1,
+    "y": 2,
+}
+
+#
+# Internal global constants
+#
+
+# Tokens
+(
+    _T_ALLNOCONFIG_Y,
+    _T_AND,
+    _T_BOOL,
+    _T_CHOICE,
+    _T_CLOSE_PAREN,
+    _T_COMMENT,
+    _T_CONFIG,
+    _T_DEFAULT,
+    _T_DEFCONFIG_LIST,
+    _T_DEF_BOOL,
+    _T_DEF_TRISTATE,
+    _T_DEPENDS,
+    _T_ENDCHOICE,
+    _T_ENDIF,
+    _T_ENDMENU,
+    _T_ENV,
+    _T_EQUAL,
+    _T_GREATER,
+    _T_GREATER_EQUAL,
+    _T_HELP,
+    _T_HEX,
+    _T_IF,
+    _T_IMPLY,
+    _T_INT,
+    _T_LESS,
+    _T_LESS_EQUAL,
+    _T_MAINMENU,
+    _T_MENU,
+    _T_MENUCONFIG,
+    _T_MODULES,
+    _T_NOT,
+    _T_ON,
+    _T_OPEN_PAREN,
+    _T_OPTION,
+    _T_OPTIONAL,
+    _T_OR,
+    _T_PROMPT,
+    _T_RANGE,
+    _T_SELECT,
+    _T_SOURCE,
+    _T_STRING,
+    _T_TRISTATE,
+    _T_UNEQUAL,
+    _T_VISIBLE,
+) = range(44)
+
+# Keyword to token map, with the get() method assigned directly as a small
+# optimization
+_get_keyword = {
+    "allnoconfig_y":  _T_ALLNOCONFIG_Y,
+    "bool":           _T_BOOL,
+    "boolean":        _T_BOOL,
+    "choice":         _T_CHOICE,
+    "comment":        _T_COMMENT,
+    "config":         _T_CONFIG,
+    "def_bool":       _T_DEF_BOOL,
+    "def_tristate":   _T_DEF_TRISTATE,
+    "default":        _T_DEFAULT,
+    "defconfig_list": _T_DEFCONFIG_LIST,
+    "depends":        _T_DEPENDS,
+    "endchoice":      _T_ENDCHOICE,
+    "endif":          _T_ENDIF,
+    "endmenu":        _T_ENDMENU,
+    "env":            _T_ENV,
+    "help":           _T_HELP,
+    "hex":            _T_HEX,
+    "if":             _T_IF,
+    "imply":          _T_IMPLY,
+    "int":            _T_INT,
+    "mainmenu":       _T_MAINMENU,
+    "menu":           _T_MENU,
+    "menuconfig":     _T_MENUCONFIG,
+    "modules":        _T_MODULES,
+    "on":             _T_ON,
+    "option":         _T_OPTION,
+    "optional":       _T_OPTIONAL,
+    "prompt":         _T_PROMPT,
+    "range":          _T_RANGE,
+    "select":         _T_SELECT,
+    "source":         _T_SOURCE,
+    "string":         _T_STRING,
+    "tristate":       _T_TRISTATE,
+    "visible":        _T_VISIBLE,
+}.get
+
+# Tokens after which identifier-like lexemes are treated as strings. _T_CHOICE
+# is included to avoid symbols being registered for named choices.
+_STRING_LEX = frozenset((
+    _T_BOOL,
+    _T_CHOICE,
+    _T_COMMENT,
+    _T_HEX,
+    _T_INT,
+    _T_MAINMENU,
+    _T_MENU,
+    _T_PROMPT,
+    _T_SOURCE,
+    _T_STRING,
+    _T_TRISTATE,
+))
+
+# Tokens for types, excluding def_bool, def_tristate, etc., for quick
+# checks during parsing
+_TYPE_TOKENS = frozenset((
+    _T_BOOL,
+    _T_TRISTATE,
+    _T_INT,
+    _T_HEX,
+    _T_STRING,
+))
+
+# Note: This hack is no longer needed as of upstream commit c226456
+# (kconfig: warn of unhandled characters in Kconfig commands). It
+# is kept around for backwards compatibility.
+#
+# The initial word on a line is parsed specially. Let
+# command_chars = [A-Za-z0-9_]. Then
+#  - leading non-command_chars characters are ignored, and
+#  - the first token consists the following one or more
+#    command_chars characters.
+# This is why things like "----help--" are accepted.
+#
+# In addition to the initial token, the regex also matches trailing whitespace
+# so that we can jump straight to the next token (or to the end of the line if
+# there's just a single token).
+#
+# As an optimization, this regex fails to match for lines containing just a
+# comment.
+_initial_token_re_match = re.compile(r"[^\w#]*(\w+)\s*").match
+
+# Matches an identifier/keyword, also eating trailing whitespace
+_id_keyword_re_match = re.compile(r"([\w./-]+)\s*").match
+
+# Regular expression for finding $-references to symbols in strings
+_sym_ref_re_search = re.compile(r"\$([A-Za-z0-9_]+)").search
+
+# Matches a valid right-hand side for an assignment to a string symbol in a
+# .config file, including escaped characters. Extracts the contents.
+_conf_string_re_match = re.compile(r'"((?:[^\\"]|\\.)*)"').match
+
+# Token to type mapping
+_TOKEN_TO_TYPE = {
+    _T_BOOL:         BOOL,
+    _T_DEF_BOOL:     BOOL,
+    _T_DEF_TRISTATE: TRISTATE,
+    _T_HEX:          HEX,
+    _T_INT:          INT,
+    _T_STRING:       STRING,
+    _T_TRISTATE:     TRISTATE,
+}
+
+# Constant representing that there's no cached choice selection. This is
+# distinct from a cached None (no selection). We create a unique object (any
+# will do) for it so we can test with 'is'.
+_NO_CACHED_SELECTION = object()
+
+# Used in comparisons. 0 means the base is inferred from the format of the
+# string. The entries for BOOL and TRISTATE are an implementation convenience:
+# They should never convert to valid numbers.
+_TYPE_TO_BASE = {
+    BOOL:     0,
+    HEX:      16,
+    INT:      10,
+    STRING:   0,
+    TRISTATE: 0,
+    UNKNOWN:  0,
+}
+
+_RELATIONS = frozenset((
+    EQUAL,
+    UNEQUAL,
+    LESS,
+    LESS_EQUAL,
+    GREATER,
+    GREATER_EQUAL,
+))
+
+# Token to relation (=, !=, <, ...) mapping
+_TOKEN_TO_REL = {
+    _T_EQUAL:         EQUAL,
+    _T_GREATER:       GREATER,
+    _T_GREATER_EQUAL: GREATER_EQUAL,
+    _T_LESS:          LESS,
+    _T_LESS_EQUAL:    LESS_EQUAL,
+    _T_UNEQUAL:       UNEQUAL,
+}
+
+_REL_TO_STR = {
+    EQUAL:         "=",
+    GREATER:       ">",
+    GREATER_EQUAL: ">=",
+    LESS:          "<",
+    LESS_EQUAL:    "<=",
+    UNEQUAL:       "!=",
+}

From c671a0c3ebf90f18576d6db55b51b62730c58301 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 12 Jan 2018 13:49:13 +1100
Subject: [PATCH 002/112] build system: Initial cmake support, work in progress

---
 Kconfig                                       |  13 +-
 components/app_trace/CMakeLists.txt           |   1 +
 components/app_update/CMakeLists.txt          |   1 +
 components/aws_iot/CMakeLists.txt             |   9 ++
 components/bootloader/CMakeLists.txt          |   2 +
 .../bootloader/subproject/CMakeLists.txt      |  26 ++++
 components/bootloader_support/CMakeLists.txt  |   9 ++
 .../include/esp_flash_encrypt.h               |   2 +
 components/bt/CMakeLists.txt                  |  99 +++++++++++++
 components/coap/CMakeLists.txt                |  33 +++++
 components/console/CMakeLists.txt             |   3 +
 components/cxx/CMakeLists.txt                 |   9 ++
 components/driver/CMakeLists.txt              |   3 +
 components/esp32/CMakeLists.txt               |  58 ++++++++
 components/esp_adc_cal/CMakeLists.txt         |   1 +
 components/esptool_py/CMakeLists.txt          |   1 +
 components/ethernet/CMakeLists.txt            |   3 +
 components/expat/CMakeLists.txt               |  14 ++
 components/fatfs/CMakeLists.txt               |   4 +
 components/freertos/CMakeLists.txt            |   5 +
 components/heap/CMakeLists.txt                |  17 +++
 components/idf_test/CMakeLists.txt            |   2 +
 components/jsmn/CMakeLists.txt                |   2 +
 components/json/CMakeLists.txt                |   4 +
 components/libsodium/CMakeLists.txt           | 104 ++++++++++++++
 components/log/CMakeLists.txt                 |   1 +
 components/lwip/CMakeLists.txt                |  37 +++++
 components/mbedtls/CMakeLists.txt             |   8 ++
 components/mdns/CMakeLists.txt                |   2 +
 components/micro-ecc/CMakeLists.txt           |   8 ++
 components/newlib/CMakeLists.txt              |  20 +++
 components/nghttp/CMakeLists.txt              |   5 +
 components/nvs_flash/CMakeLists.txt           |   4 +
 components/openssl/CMakeLists.txt             |   5 +
 components/partition_table/CMakeLists.txt     |   1 +
 components/pthread/CMakeLists.txt             |   3 +
 components/sdmmc/CMakeLists.txt               |   1 +
 components/smartconfig/CMakeLists.txt         |   4 +
 components/soc/CMakeLists.txt                 |   6 +
 components/spi_flash/CMakeLists.txt           |  11 ++
 components/spiffs/CMakeLists.txt              |   6 +
 components/tcpip_adapter/CMakeLists.txt       |   1 +
 components/ulp/CMakeLists.txt                 |   1 +
 components/vfs/CMakeLists.txt                 |   1 +
 components/wear_levelling/CMakeLists.txt      |   2 +
 components/wpa_supplicant/CMakeLists.txt      |   7 +
 components/xtensa-debug-module/CMakeLists.txt |   1 +
 .../get-started/hello_world/CMakeLists.txt    |  12 ++
 idf.cmake                                     |  78 ++++++++++
 toolchain.cmake                               |  11 ++
 tools/cmake/GetGitRevisionDescription.cmake   | 130 +++++++++++++++++
 .../cmake/GetGitRevisionDescription.cmake.in  |  41 ++++++
 tools/cmake/bootloader_subproject.cmake       |  13 ++
 tools/cmake/components.cmake                  | 133 ++++++++++++++++++
 tools/cmake/kconfig.cmake                     |  82 +++++++++++
 tools/cmake/utilities.cmake                   |  60 ++++++++
 56 files changed, 1115 insertions(+), 5 deletions(-)
 create mode 100644 components/app_trace/CMakeLists.txt
 create mode 100644 components/app_update/CMakeLists.txt
 create mode 100644 components/aws_iot/CMakeLists.txt
 create mode 100644 components/bootloader/CMakeLists.txt
 create mode 100644 components/bootloader/subproject/CMakeLists.txt
 create mode 100644 components/bootloader_support/CMakeLists.txt
 create mode 100644 components/bt/CMakeLists.txt
 create mode 100644 components/coap/CMakeLists.txt
 create mode 100644 components/console/CMakeLists.txt
 create mode 100644 components/cxx/CMakeLists.txt
 create mode 100644 components/driver/CMakeLists.txt
 create mode 100644 components/esp32/CMakeLists.txt
 create mode 100644 components/esp_adc_cal/CMakeLists.txt
 create mode 100644 components/esptool_py/CMakeLists.txt
 create mode 100644 components/ethernet/CMakeLists.txt
 create mode 100644 components/expat/CMakeLists.txt
 create mode 100644 components/fatfs/CMakeLists.txt
 create mode 100644 components/freertos/CMakeLists.txt
 create mode 100644 components/heap/CMakeLists.txt
 create mode 100644 components/idf_test/CMakeLists.txt
 create mode 100644 components/jsmn/CMakeLists.txt
 create mode 100644 components/json/CMakeLists.txt
 create mode 100644 components/libsodium/CMakeLists.txt
 create mode 100644 components/log/CMakeLists.txt
 create mode 100644 components/lwip/CMakeLists.txt
 create mode 100644 components/mbedtls/CMakeLists.txt
 create mode 100644 components/mdns/CMakeLists.txt
 create mode 100644 components/micro-ecc/CMakeLists.txt
 create mode 100644 components/newlib/CMakeLists.txt
 create mode 100644 components/nghttp/CMakeLists.txt
 create mode 100644 components/nvs_flash/CMakeLists.txt
 create mode 100644 components/openssl/CMakeLists.txt
 create mode 100644 components/partition_table/CMakeLists.txt
 create mode 100644 components/pthread/CMakeLists.txt
 create mode 100644 components/sdmmc/CMakeLists.txt
 create mode 100644 components/smartconfig/CMakeLists.txt
 create mode 100644 components/soc/CMakeLists.txt
 create mode 100644 components/spi_flash/CMakeLists.txt
 create mode 100644 components/spiffs/CMakeLists.txt
 create mode 100644 components/tcpip_adapter/CMakeLists.txt
 create mode 100644 components/ulp/CMakeLists.txt
 create mode 100644 components/vfs/CMakeLists.txt
 create mode 100644 components/wear_levelling/CMakeLists.txt
 create mode 100644 components/wpa_supplicant/CMakeLists.txt
 create mode 100644 components/xtensa-debug-module/CMakeLists.txt
 create mode 100644 examples/get-started/hello_world/CMakeLists.txt
 create mode 100644 idf.cmake
 create mode 100644 toolchain.cmake
 create mode 100644 tools/cmake/GetGitRevisionDescription.cmake
 create mode 100644 tools/cmake/GetGitRevisionDescription.cmake.in
 create mode 100644 tools/cmake/bootloader_subproject.cmake
 create mode 100644 tools/cmake/components.cmake
 create mode 100644 tools/cmake/kconfig.cmake
 create mode 100644 tools/cmake/utilities.cmake

diff --git a/Kconfig b/Kconfig
index 6dfaa3183..b1498870a 100644
--- a/Kconfig
+++ b/Kconfig
@@ -121,11 +121,14 @@ choice STACK_CHECK_MODE
         smashing attacks. This is done by adding a guard variable to functions with vulnerable objects.
         The guards are initialized when a function is entered and then checked when the function exits.
         If a guard check fails, program is halted. Protection has the following modes:
-          - In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca, and functions with buffers larger than
-            8 bytes are protected.
-          - STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes additional functions to be protected -- those that
-            have local array definitions, or have references to local frame addresses.
-          - In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected.
+
+          - In NORMAL mode (GCC flag: -fstack-protector) only functions that call
+            alloca, and functions with buffers larger than 8 bytes are protected.
+          - STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but
+            includes additional functions to be protected -- those that have
+            local array definitions, or have references to local frame addresses.
+          - In OVERALL mode (GCC flag: -fstack-protector-all) all functions are
+            protected.
 
         Modes have the following impact on code performance and coverage:
           - performance: NORMAL > STRONG > OVERALL
diff --git a/components/app_trace/CMakeLists.txt b/components/app_trace/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/app_trace/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/app_update/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/aws_iot/CMakeLists.txt b/components/aws_iot/CMakeLists.txt
new file mode 100644
index 000000000..29909bd14
--- /dev/null
+++ b/components/aws_iot/CMakeLists.txt
@@ -0,0 +1,9 @@
+if(CONFIG_AWS_IOT_SDK)
+
+set(COMPONENT_ADD_INCLUDEDIRS "include aws-iot-device-sdk-embedded-C/include")
+set(COMPONENT_SRCDIRS "aws-iot-device-sdk-embedded-C/src port")
+set(COMPONENT_SUBMODULES aws-iot-device-sdk-embedded-C)
+
+register_component()
+
+endif(CONFIG_AWS_IOT_SDK)
diff --git a/components/bootloader/CMakeLists.txt b/components/bootloader/CMakeLists.txt
new file mode 100644
index 000000000..1b694f381
--- /dev/null
+++ b/components/bootloader/CMakeLists.txt
@@ -0,0 +1,2 @@
+# TODO: add config stuff for bootloader here
+
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
new file mode 100644
index 000000000..e8f920f2e
--- /dev/null
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -0,0 +1,26 @@
+cmake_minimum_required(VERSION 3.5)
+set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
+project(idf_bootloader ASM C CXX)
+
+set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash micro-ecc soc)
+
+set(BOOTLOADER_BUILD 1)
+set(IS_BOOTLOADER_BUILD 1)  # deprecated, use BOOTLOADER_BUILD
+add_definitions(-DBOOTLOADER_BUILD=1)
+
+if(NOT SDKCONFIG)
+  message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the app build process.")
+endif()
+
+include($ENV{IDF_PATH}/idf.cmake)
+
+add_executable(bootloader.elf
+  main/bootloader_start.c
+  main/flash_qio_mode.c)
+
+target_link_libraries(bootloader.elf ${COMPONENT_LIBRARIES})
+
+target_link_libraries(bootloader.elf "-L ${CMAKE_CURRENT_SOURCE_DIR}/main")
+target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
+target_link_libraries(bootloader.elf "-T esp32.bootloader.rom.ld")
+target_link_libraries(bootloader.elf "${BOOTLOADER_LINKER_ARGS}")
diff --git a/components/bootloader_support/CMakeLists.txt b/components/bootloader_support/CMakeLists.txt
new file mode 100644
index 000000000..f27310dfc
--- /dev/null
+++ b/components/bootloader_support/CMakeLists.txt
@@ -0,0 +1,9 @@
+set(COMPONENT_SRCDIRS "src")
+
+if(${BOOTLOADER_BUILD})
+  set(COMPONENT_ADD_INCLUDEDIRS "include include_priv")
+else()
+  set(COMPONENT_PRIV_INCLUDEDIRS "include_priv")
+endif()
+
+register_component()
diff --git a/components/bootloader_support/include/esp_flash_encrypt.h b/components/bootloader_support/include/esp_flash_encrypt.h
index ba370644a..31b77a734 100644
--- a/components/bootloader_support/include/esp_flash_encrypt.h
+++ b/components/bootloader_support/include/esp_flash_encrypt.h
@@ -17,7 +17,9 @@
 #include <stdbool.h>
 #include "esp_attr.h"
 #include "esp_err.h"
+#ifndef BOOTLOADER_BUILD
 #include "esp_spi_flash.h"
+#endif
 #include "soc/efuse_reg.h"
 
 /**
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
new file mode 100644
index 000000000..7410e19d0
--- /dev/null
+++ b/components/bt/CMakeLists.txt
@@ -0,0 +1,99 @@
+if(CONFIG_BT_ENABLED)
+
+  set(COMPONENT_SRCDIRS .)
+  set(COMPONENT_ADD_INCLUDEDIRS include)
+
+  target_link_libraries("-L ${CMAKE_CURRENT_LIST_DIR}/lib")
+  target_link_libraries(bt btdm_app)
+
+  if(CONFIG_BLUEDROID_ENABLED)
+
+    set(COMPONENT_ADD_INCLUDEDIRS ${COMPONENT_ADD_INCLUDEDIRS}
+      bluedroid/bta/include
+	  bluedroid/bta/sys/include
+      bluedroid/btcore/include
+      bluedroid/device/include
+      bluedroid/gki/include
+      bluedroid/hci/include
+      bluedroid/osi/include
+      bluedroid/utils/include
+      bluedroid/external/sbc/decoder/include
+      bluedroid/btc/core/include
+      bluedroid/btc/profile/esp/blufi/include
+      bluedroid/btc/profile/esp/include
+      bluedroid/btc/profile/std/gatt/include
+      bluedroid/btc/profile/std/gap/include
+      bluedroid/btc/profile/std/a2dp/include
+      bluedroid/btc/profile/std/include
+      bluedroid/btc/include
+      bluedroid/btif/include
+      bluedroid/stack/btm/include
+      bluedroid/stack/btu/include
+      bluedroid/stack/gap/include
+      bluedroid/stack/gatt/include
+      bluedroid/stack/hcic/include
+      bluedroid/stack/l2cap/include
+      bluedroid/stack/sdp/include
+      bluedroid/stack/smp/include
+      bluedroid/stack/avct/include
+      bluedroid/stack/avrc/include
+      bluedroid/stack/avdt/include
+      bluedroid/stack/a2dp/include
+      bluedroid/stack/rfcomm/include
+      bluedroid/stack/include
+      bluedroid/utils/include
+      bluedroid/api/include
+      bluedroid/include)
+
+    set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+      bluedroid/bta/dm
+      bluedroid/bta/gatt
+      bluedroid/bta/hh
+      bluedroid/bta/sdp
+      bluedroid/bta/av
+      bluedroid/bta/ar
+      bluedroid/bta/sys
+      bluedroid/bta/jv
+      bluedroid/bta
+      bluedroid/btcore
+      bluedroid/btif
+      bluedroid/device
+      bluedroid/gki
+      bluedroid/hci
+      bluedroid/main
+      bluedroid/osi
+      bluedroid/external/sbc/decoder/srce
+      bluedroid/btc/core
+      bluedroid/btc/profile/esp/blufi
+      bluedroid/btc/profile/std/gap
+      bluedroid/btc/profile/std/gatt
+      bluedroid/btc/profile/std/a2dp
+      bluedroid/btc/profile/std/avrc
+      bluedroid/btc/profile/std/spp
+      bluedroid/btc/profile
+      bluedroid/stack/btm
+      bluedroid/stack/btu
+      bluedroid/stack/gap
+      bluedroid/stack/gatt
+      bluedroid/stack/hcic
+      bluedroid/stack/include
+      bluedroid/stack/l2cap
+      bluedroid/stack/sdp
+      bluedroid/stack/smp
+      bluedroid/stack/avct
+      bluedroid/stack/avrc
+      bluedroid/stack/avdt
+      bluedroid/stack/a2dp
+      bluedroid/stack/rfcomm
+      bluedroid/stack
+      bluedroid/utils
+      bluedroid/api
+      bluedroid)
+
+  endif(CONFIG_BLUEDROID_ENABLED)
+
+  register_component()
+
+endif(CONFIG_BT_ENABLED)
+
+
diff --git a/components/coap/CMakeLists.txt b/components/coap/CMakeLists.txt
new file mode 100644
index 000000000..9a9b65ccb
--- /dev/null
+++ b/components/coap/CMakeLists.txt
@@ -0,0 +1,33 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include port/include/coap libcoap/include libcoap/include/coap)
+
+set(COMPONENT_SRCS
+  libcoap/src/address.c
+  libcoap/src/async.c
+  libcoap/src/block.c
+  libcoap/src/coap_time.c
+  libcoap/src/debug.c
+  libcoap/src/encode.c
+  libcoap/src/hashkey.c
+  libcoap/src/mem.c
+  libcoap/src/net.c
+  libcoap/src/option.c
+  libcoap/src/pdu.c
+  libcoap/src/resource.c
+  libcoap/src/str.c
+  libcoap/src/subscribe.c
+  libcoap/src/uri.c
+  port/coap_io_socket.c
+  )
+
+set(COMPONENT_SUBMODULES libcoap)
+
+register_component()
+
+# Needed for coap headers in public builds, also.
+#
+# TODO: find a way to move this to a port header
+target_compile_definitions(coap PUBLIC
+	WITH_POSIX
+)
+
+
diff --git a/components/console/CMakeLists.txt b/components/console/CMakeLists.txt
new file mode 100644
index 000000000..d1187256b
--- /dev/null
+++ b/components/console/CMakeLists.txt
@@ -0,0 +1,3 @@
+set(COMPONENT_SRCDIRS linenoise argtable3 .)
+register_component()
+
diff --git a/components/cxx/CMakeLists.txt b/components/cxx/CMakeLists.txt
new file mode 100644
index 000000000..bf51565c4
--- /dev/null
+++ b/components/cxx/CMakeLists.txt
@@ -0,0 +1,9 @@
+register_component()
+
+target_link_libraries(cxx stdc++)
+
+target_link_libraries(cxx "-u __cxa_guard_dummy")
+
+if(NOT CONFIG_CXX_EXCEPTIONS)
+  target_link_libraries(cxx "-u __cxx_fatal_exception")
+endif()
diff --git a/components/driver/CMakeLists.txt b/components/driver/CMakeLists.txt
new file mode 100644
index 000000000..ca0849824
--- /dev/null
+++ b/components/driver/CMakeLists.txt
@@ -0,0 +1,3 @@
+set(COMPONENT_PRIV_INCLUDEDIRS include/driver)
+
+register_component()
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
new file mode 100644
index 000000000..9a9d4c783
--- /dev/null
+++ b/components/esp32/CMakeLists.txt
@@ -0,0 +1,58 @@
+if(BOOTLOADER_BUILD)
+  # For bootloader, all we need from esp32 is headers
+  add_library(esp32 INTERFACE)
+  target_include_directories(esp32 INTERFACE include)
+
+  # as cmake won't attach linker args to a header-only library, attach
+  # linker args directly to the bootloader.elf
+  set(BOOTLOADER_LINKER_ARGS "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld -T esp32.rom.ld -Tesp32.rom.spiram_incompatible_fns.ld -T esp32.peripherals.ld" PARENT_SCOPE)
+
+else()
+  # Regular app build
+
+  register_component()
+
+  target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
+  if(NOT CONFIG_NO_BLOBS)
+    target_link_libraries(esp32 coexist core espnow net80211 phy pp rtc smartconfig wpa2 wpa wps)
+  endif()
+  target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld")
+  target_link_libraries(esp32 "-T ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
+  target_link_libraries(esp32 "-T esp32.common.ld")
+  target_link_libraries(esp32 "-T esp32.rom.ld")
+  target_link_libraries(esp32 "-T esp32.peripherals.ld")
+
+  if(CONFIG_SPIRAM_CACHE_WORKAROUND)
+    target_link_libraries(esp32 ${CMAKE_CURRENT_SOURCE_DIR}/libstdc++-psram-workaround.a)
+  else()
+    target_link_libraries(esp32 "-T esp32.rom.spiram_incompatible_fns.ld")
+  endif()
+
+  if(CONFIG_NEWLIB_NANO_FORMAT)
+    target_link_libraries(esp32 "-T esp32.rom.nanofmt.ld")
+  endif()
+
+  if(NOT CONFIG_SPI_FLASH_ROM_DRIVER_PATCH)
+    target_link_libraries(esp32 "-T esp32.rom.spiflash.ld")
+  endif()
+
+  target_link_libraries(esp32 "${CMAKE_CURRENT_SOURCE_DIR}/libhal.a")
+  target_link_libraries(esp32 gcc)
+
+  #ld_include_panic_highint_hdl is added as an undefined symbol because otherwise the
+#linker will ignore panic_highint_hdl.S as it has no other files depending on any
+#symbols in it.
+  target_link_libraries(esp32 "-u ld_include_panic_highint_hdl")
+
+  # Preprocess esp32.ld linker script to include configuration, becomes esp32_out.ld
+  set(LD_DIR ${CMAKE_CURRENT_SOURCE_DIR}/ld)
+  add_custom_command(
+    OUTPUT esp32_out.ld
+    COMMAND "${CMAKE_C_COMPILER}" -C -P -x c -E -o esp32_out.ld -I ${CMAKE_BINARY_DIR} ${LD_DIR}/esp32.ld
+    MAIN_DEPENDENCY ${LD_DIR}/esp32.ld
+    COMMENT "Generating linker script..."
+    VERBATIM)
+  add_custom_target(esp32_linker_script DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld)
+  add_dependencies(esp32 esp32_linker_script)
+
+endif()
diff --git a/components/esp_adc_cal/CMakeLists.txt b/components/esp_adc_cal/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/esp_adc_cal/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
new file mode 100644
index 000000000..bdd55ceea
--- /dev/null
+++ b/components/esptool_py/CMakeLists.txt
@@ -0,0 +1 @@
+register_config_only_component()
diff --git a/components/ethernet/CMakeLists.txt b/components/ethernet/CMakeLists.txt
new file mode 100644
index 000000000..4e20fbead
--- /dev/null
+++ b/components/ethernet/CMakeLists.txt
@@ -0,0 +1,3 @@
+set(COMPONENT_SRCDIRS . eth_phy)
+
+register_component()
diff --git a/components/expat/CMakeLists.txt b/components/expat/CMakeLists.txt
new file mode 100644
index 000000000..02445015c
--- /dev/null
+++ b/components/expat/CMakeLists.txt
@@ -0,0 +1,14 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include include/expat)
+
+set(COMPONENT_SRCDIRS library port)
+
+register_component()
+
+target_compile_definitions(expat PRIVATE HAVE_EXPAT_CONFIG_H)
+
+# patch around warnings in third-party files
+set_source_files_properties(
+  library/xmlparse.c
+  PROPERTIES COMPILE_FLAGS
+  -Wno-unused-function
+  )
diff --git a/components/fatfs/CMakeLists.txt b/components/fatfs/CMakeLists.txt
new file mode 100644
index 000000000..2f3a88826
--- /dev/null
+++ b/components/fatfs/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(COMPONENT_ADD_INCLUDEDIRS src)
+set(COMPONENT_SRCDIRS src/option src)
+
+register_component()
diff --git a/components/freertos/CMakeLists.txt b/components/freertos/CMakeLists.txt
new file mode 100644
index 000000000..1c6a9523b
--- /dev/null
+++ b/components/freertos/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_PRIV_INCLUDEDIRS include/freertos)
+register_component()
+
+target_link_libraries(freertos "-Wl,--undefined=uxTopUsedPriority")
diff --git a/components/heap/CMakeLists.txt b/components/heap/CMakeLists.txt
new file mode 100644
index 000000000..015daa9b7
--- /dev/null
+++ b/components/heap/CMakeLists.txt
@@ -0,0 +1,17 @@
+set(COMPONENT_SRCS heap_caps_init.c heap_caps.c multi_heap.c heap_trace.c)
+
+if(NOT CONFIG_HEAP_POISONING_DISABLED)
+  set(COMPONENT_SRCS ${COMPONENT_SRCS} multi_heap_poisoning.c)
+endif()
+
+register_component()
+
+if(CONFIG_HEAP_TRACING)
+  set(WRAP_FUNCTIONS
+    calloc malloc free realloc heap_caps_malloc heap_caps_free heap_caps_realloc)
+
+  foreach(wrap ${WRAP_FUNCTIONS})
+    target_link_libraries(heap "-Wl,--wrap=${wrap}")
+  endforeach()
+
+endif(CONFIG_HEAP_TRACING)
diff --git a/components/idf_test/CMakeLists.txt b/components/idf_test/CMakeLists.txt
new file mode 100644
index 000000000..131acae4d
--- /dev/null
+++ b/components/idf_test/CMakeLists.txt
@@ -0,0 +1,2 @@
+# idf_test will be registered as an INTERFACE library (ie header paths only)
+register_component()
diff --git a/components/jsmn/CMakeLists.txt b/components/jsmn/CMakeLists.txt
new file mode 100644
index 000000000..817f6e4be
--- /dev/null
+++ b/components/jsmn/CMakeLists.txt
@@ -0,0 +1,2 @@
+set(COMPONENT_SRCDIRS src)
+register_component()
diff --git a/components/json/CMakeLists.txt b/components/json/CMakeLists.txt
new file mode 100644
index 000000000..e3559b269
--- /dev/null
+++ b/components/json/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(COMPONENT_SRCDIRS library port)
+set(COMPONENT_ADD_INCLUDEDIRS include port/include)
+
+register_component()
diff --git a/components/libsodium/CMakeLists.txt b/components/libsodium/CMakeLists.txt
new file mode 100644
index 000000000..78ab23c64
--- /dev/null
+++ b/components/libsodium/CMakeLists.txt
@@ -0,0 +1,104 @@
+set(SRC libsodium/src/libsodium)
+
+set(COMPONENT_SUBMODULES libsodium)
+
+set(COMPONENT_SRCDIRS
+  port
+
+  # Derived from libsodium/src/libsodium/Makefile.am
+  # (ignoring the !MINIMAL set)
+  ${SRC}/crypto_aead/chacha20poly1305/sodium
+  ${SRC}/crypto_aead/xchacha20poly1305/sodium
+  ${SRC}/crypto_auth
+  ${SRC}/crypto_auth/hmacsha256
+  ${SRC}/crypto_auth/hmacsha512
+  ${SRC}/crypto_auth/hmacsha512256
+  ${SRC}/crypto_box
+  ${SRC}/crypto_box/curve25519xsalsa20poly1305
+  ${SRC}/crypto_core/curve25519/ref10
+  ${SRC}/crypto_core/hchacha20
+  ${SRC}/crypto_core/hsalsa20/ref2
+  ${SRC}/crypto_core/hsalsa20
+  ${SRC}/crypto_core/salsa/ref
+  ${SRC}/crypto_generichash
+  ${SRC}/crypto_generichash/blake2b
+  ${SRC}/crypto_generichash/blake2b/ref
+  ${SRC}/crypto_hash
+  ${SRC}/crypto_hash/sha256
+  ${SRC}/crypto_hash/sha512
+  ${SRC}/crypto_kdf/blake2b
+  ${SRC}/crypto_kdf
+  ${SRC}/crypto_kx
+  ${SRC}/crypto_onetimeauth
+  ${SRC}/crypto_onetimeauth/poly1305
+  ${SRC}/crypto_onetimeauth/poly1305/donna
+  ${SRC}/crypto_pwhash/argon2
+  ${SRC}/crypto_pwhash
+  ${SRC}/crypto_pwhash/scryptsalsa208sha256
+  ${SRC}/crypto_pwhash/scryptsalsa208sha256/nosse
+  ${SRC}/crypto_scalarmult
+  ${SRC}/crypto_scalarmult/curve25519
+  ${SRC}/crypto_scalarmult/curve25519/ref10
+  ${SRC}/crypto_secretbox
+  ${SRC}/crypto_secretbox/xsalsa20poly1305
+  ${SRC}/crypto_shorthash
+  ${SRC}/crypto_shorthash/siphash24
+  ${SRC}/crypto_shorthash/siphash24/ref
+  ${SRC}/crypto_sign
+  ${SRC}/crypto_sign/ed25519
+  ${SRC}/crypto_sign/ed25519/ref10
+  ${SRC}/crypto_stream/chacha20
+  ${SRC}/crypto_stream/chacha20/ref
+  ${SRC}/crypto_stream
+  ${SRC}/crypto_stream/salsa20
+  ${SRC}/crypto_stream/salsa20/ref
+  ${SRC}/crypto_stream/xsalsa20
+  ${SRC}/crypto_verify/sodium
+  ${SRC}/randombytes
+  ${SRC}/sodium
+  )
+
+if(CONFIG_LIBSODIUM_USE_MBEDTLS_SHA)
+  set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+    port/crypto_hash_mbedtls
+    )
+else()
+  set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+    ${SRC}/crypto_hash/sha256/cp
+    ${SRC}/crypto_hash/sha512/cp
+    )
+endif()
+
+set(COMPONENT_ADD_INCLUDEDIRS ${SRC}/include port_include)
+set(COMPONENT_PRIV_INCLUDEDIRS ${SRC}/include/sodium port_include/sodium port)
+
+register_component()
+
+target_compile_definitions(libsodium PRIVATE
+	CONFIGURED
+	NATIVE_LITTLE_ENDIAN
+	HAVE_WEAK_SYMBOLS
+	__STDC_LIMIT_MACROS
+	__STDC_CONSTANT_MACROS
+)
+
+target_compile_options(libsodium PRIVATE
+	-Wno-unknown-pragmas
+    )
+
+# patch around warnings in third-party files
+set_source_files_properties(
+  ${SRC}/crypto_pwhash/argon2/argon2-fill-block-ref.c
+  ${SRC}/crypto_pwhash/argon2/pwhash_argon2i.c
+  ${SRC}/crypto_pwhash/argon2/argon2-core.c
+  ${SRC}/crypto_pwhash/scryptsalsa208sha256/pwhash_scryptsalsa208sha256.c
+  PROPERTIES COMPILE_FLAGS
+  -Wno-type-limits
+  )
+set_source_files_properties(
+  ${SRC}/sodium/utils.c
+  PROPERTIES COMPILE_FLAGS
+  -Wno-unused-variable
+  )
+
+
diff --git a/components/log/CMakeLists.txt b/components/log/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/log/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
new file mode 100644
index 000000000..1ffa69f47
--- /dev/null
+++ b/components/lwip/CMakeLists.txt
@@ -0,0 +1,37 @@
+set(COMPONENT_ADD_INCLUDEDIRS
+	include/lwip
+	include/lwip/port
+	include/lwip/posix
+	apps/ping
+    )
+
+if(CONFIG_PPP_SUPPORT)
+set(LWIP_PPP_DIRS netif/ppp/polarssl netif/ppp)
+endif()
+
+set(COMPONENT_SRCDIRS
+	api
+	apps apps/sntp apps/ping
+	core core/ipv4 core/ipv6
+	${LWIP_PPP_DIRS} netif
+	port/freertos port/netif port/debug port)
+
+register_component()
+
+target_compile_options(lwip PRIVATE
+	-Wno-address
+)
+
+# patch around warnings in third-party files
+set_source_files_properties(api/tcpip.c
+  PROPERTIES COMPILE_FLAGS
+  -Wno-unused-variable
+  )
+set_source_files_properties(core/pbuf.c core/tcp_in.c
+  PROPERTIES COMPILE_FLAGS
+  -Wno-unused-but-set-variable
+  )
+set_source_files_properties(apps/dhcpserver.c
+  PROPERTIES COMPILE_FLAGS
+  "-Wno-unused-variable -Wno-unused-but-set-variable -Wno-type-limits"
+  )
diff --git a/components/mbedtls/CMakeLists.txt b/components/mbedtls/CMakeLists.txt
new file mode 100644
index 000000000..96ac14d12
--- /dev/null
+++ b/components/mbedtls/CMakeLists.txt
@@ -0,0 +1,8 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include include)
+set(COMPONENT_SRCDIRS library port)
+
+register_component()
+
+target_compile_definitions(mbedtls PUBLIC
+	MBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
+)
diff --git a/components/mdns/CMakeLists.txt b/components/mdns/CMakeLists.txt
new file mode 100644
index 000000000..0ba2e49dc
--- /dev/null
+++ b/components/mdns/CMakeLists.txt
@@ -0,0 +1,2 @@
+register_component()
+
diff --git a/components/micro-ecc/CMakeLists.txt b/components/micro-ecc/CMakeLists.txt
new file mode 100644
index 000000000..6ae9c8ae3
--- /dev/null
+++ b/components/micro-ecc/CMakeLists.txt
@@ -0,0 +1,8 @@
+# only compile the micro-ecc/uECC.c source file
+set(COMPONENT_SRCS micro-ecc/uECC.c)
+
+set(COMPONENT_ADD_INCLUDEDIRS micro-ecc)
+
+set(COMPONENT_SUBMODULES micro-ecc)
+
+register_component()
diff --git a/components/newlib/CMakeLists.txt b/components/newlib/CMakeLists.txt
new file mode 100644
index 000000000..0fa454cba
--- /dev/null
+++ b/components/newlib/CMakeLists.txt
@@ -0,0 +1,20 @@
+set(COMPONENT_ADD_INCLUDEDIRS platform_include include)
+
+if(CONFIG_SPIRAM_CACHE_WORKAROUND)
+  set(LIBC c-psram-workaround)
+  set(LIBM m-psram-workaround)
+else()
+
+  if(CONFIG_NEWLIB_NANO_FORMAT)
+    set(LIBC c_nano)
+  else()
+    set(LIBC c)
+  endif(CONFIG_NEWLIB_NANO_FORMAT)
+
+  set(LIBM m)
+endif(CONFIG_SPIRAM_CACHE_WORKAROUND)
+
+register_component()
+
+target_link_libraries(newlib "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
+target_link_libraries(newlib ${LIBC} ${LIBM})
diff --git a/components/nghttp/CMakeLists.txt b/components/nghttp/CMakeLists.txt
new file mode 100644
index 000000000..1a549b075
--- /dev/null
+++ b/components/nghttp/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include nghttp2/lib/includes)
+set(COMPONENT_SRCDIRS nghttp2/lib port)
+set(COMPONENT_SUBMODULES nghttp2)
+
+register_component()
diff --git a/components/nvs_flash/CMakeLists.txt b/components/nvs_flash/CMakeLists.txt
new file mode 100644
index 000000000..7a9584c6d
--- /dev/null
+++ b/components/nvs_flash/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_SRCDIRS src)
+
+register_component()
diff --git a/components/openssl/CMakeLists.txt b/components/openssl/CMakeLists.txt
new file mode 100644
index 000000000..347ade638
--- /dev/null
+++ b/components/openssl/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_PRIV_INCLUDEDIRS include/internal include/platform include/openssl)
+set(COMPONENT_SRCDIRS library platform)
+
+register_component()
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
new file mode 100644
index 000000000..bdd55ceea
--- /dev/null
+++ b/components/partition_table/CMakeLists.txt
@@ -0,0 +1 @@
+register_config_only_component()
diff --git a/components/pthread/CMakeLists.txt b/components/pthread/CMakeLists.txt
new file mode 100644
index 000000000..eebd20a04
--- /dev/null
+++ b/components/pthread/CMakeLists.txt
@@ -0,0 +1,3 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+register_component()
diff --git a/components/sdmmc/CMakeLists.txt b/components/sdmmc/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/sdmmc/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/smartconfig/CMakeLists.txt b/components/smartconfig/CMakeLists.txt
new file mode 100644
index 000000000..ba2fa9c7e
--- /dev/null
+++ b/components/smartconfig/CMakeLists.txt
@@ -0,0 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+register_component()
diff --git a/components/soc/CMakeLists.txt b/components/soc/CMakeLists.txt
new file mode 100644
index 000000000..24e859551
--- /dev/null
+++ b/components/soc/CMakeLists.txt
@@ -0,0 +1,6 @@
+set(SOC_NAME esp32)
+
+set(COMPONENT_SRCDIRS ${SOC_NAME})
+set(COMPONENT_ADD_INCLUDEDIRS ${SOC_NAME}/include include)
+
+register_component()
diff --git a/components/spi_flash/CMakeLists.txt b/components/spi_flash/CMakeLists.txt
new file mode 100644
index 000000000..2b2622261
--- /dev/null
+++ b/components/spi_flash/CMakeLists.txt
@@ -0,0 +1,11 @@
+if(BOOTLOADER_BUILD)
+  # Bootloader needs SPIUnlock from this file, but doesn't
+  # need other parts of this component
+  set(COMPONENT_SRCS spi_flash_rom_patch.c)
+else()
+  set(COMPONENT_SRCDIRS .)
+endif()
+
+set(COMPONENT_ADD_INCLUDEDIRS include)
+
+register_component()
diff --git a/components/spiffs/CMakeLists.txt b/components/spiffs/CMakeLists.txt
new file mode 100644
index 000000000..0435a38b6
--- /dev/null
+++ b/components/spiffs/CMakeLists.txt
@@ -0,0 +1,6 @@
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS "spiffs/src")
+set(COMPONENT_SRCDIRS ". spiffs/src")
+set(COMPONENT_SUBMODULES "spiffs")
+register_component()
+
diff --git a/components/tcpip_adapter/CMakeLists.txt b/components/tcpip_adapter/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/tcpip_adapter/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/ulp/CMakeLists.txt b/components/ulp/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/ulp/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/vfs/CMakeLists.txt b/components/vfs/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/vfs/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/components/wear_levelling/CMakeLists.txt b/components/wear_levelling/CMakeLists.txt
new file mode 100644
index 000000000..f4f2f14ec
--- /dev/null
+++ b/components/wear_levelling/CMakeLists.txt
@@ -0,0 +1,2 @@
+set(COMPONENT_PRIV_INCLUDEDIRS private_include)
+register_component()
diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
new file mode 100644
index 000000000..73c7294a6
--- /dev/null
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -0,0 +1,7 @@
+set(COMPONENT_ADD_INCLUDEDIRS include port/include)
+set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto)
+
+register_component()
+
+target_compile_definitions(wpa_supplicant PRIVATE __ets__)
+target_compile_options(wpa_supplicant PRIVATE -Wno-strict-aliasing)
diff --git a/components/xtensa-debug-module/CMakeLists.txt b/components/xtensa-debug-module/CMakeLists.txt
new file mode 100644
index 000000000..339733b43
--- /dev/null
+++ b/components/xtensa-debug-module/CMakeLists.txt
@@ -0,0 +1 @@
+register_component()
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
new file mode 100644
index 000000000..62a03947f
--- /dev/null
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -0,0 +1,12 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
+project(idf_project ASM C CXX)
+
+include($ENV{IDF_PATH}/idf.cmake)
+
+add_executable(hello_world.elf
+  main/hello_world_main.c)
+
+target_link_libraries(hello_world.elf ${COMPONENT_LIBRARIES})
diff --git a/idf.cmake b/idf.cmake
new file mode 100644
index 000000000..8586d687a
--- /dev/null
+++ b/idf.cmake
@@ -0,0 +1,78 @@
+# Designed to be included from an IDF app's CMakeLists.txt file
+#
+cmake_minimum_required(VERSION 3.5)
+
+#
+# Verify the project configured the environment correctly
+#
+if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
+  message(FATAL_ERROR "The parent project CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
+    "before including this file. "
+    "Update CMakeLists.txt to match the template project and delete CMakeCache.txt before "
+    "re-running cmake.")
+endif()
+
+set(IDF_PATH $ENV{IDF_PATH})
+if(NOT IDF_PATH)
+  # Documentation says you should set IDF_PATH in your environment, but we
+  # can infer it here if it's not set.
+  set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
+endif()
+
+# PROJECT_PATH has the path to the IDF project (top-level cmake directory)
+#
+# (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
+set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
+
+#
+# Load cmake modules
+#
+set(CMAKE_MODULE_PATH "${IDF_PATH}/tools/cmake" ${CMAKE_MODULE_PATH})
+include(GetGitRevisionDescription)
+include(utilities)
+include(components)
+include(kconfig)
+
+#
+# Configure optional variables
+#
+set_default(EXTRA_COMPONENT_DIRS "")
+
+# Note: "main" is no longer a component...
+#
+set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
+spaces2list(COMPONENT_DIRS)
+
+# expand COMPONENT_DIRS variable into full paths to all components and their names
+spaces2list(COMPONENTS)
+find_all_components("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
+build_component_config()
+
+# Include sdkconfig.cmake so rest of the build knows the configuration
+include(${SDKCONFIG_CMAKE})
+
+#
+# Add some idf-wide definitions
+#
+add_definitions(-DESP_PLATFORM)
+add_definitions(-DHAVE_CONFIG_H)
+
+git_describe(GIT_REVISION)
+add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
+
+add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
+
+#
+# Add components to the build
+#
+foreach(component ${COMPONENT_PATHS})
+  get_filename_component(component_name ${component} NAME)
+  add_subdirectory(${component} ${component_name})
+endforeach()
+
+finish_component_registration()
+
+# Load the targets for the bootloader subproject
+if(NOT BOOTLOADER_BUILD)
+  include(bootloader_subproject)
+endif()
diff --git a/toolchain.cmake b/toolchain.cmake
new file mode 100644
index 000000000..12e3f5a5a
--- /dev/null
+++ b/toolchain.cmake
@@ -0,0 +1,11 @@
+set(CMAKE_SYSTEM_NAME Generic)
+
+set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
+set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
+set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
+
+set(CMAKE_C_FLAGS_INIT "-Og -ggdb -std=gnu99 -ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib -Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare -Wno-old-style-declaration")
+set(CMAKE_CXX_FLAGS_INIT "-Og -ggdb -std=gnu++11 -fno-exceptions -fno-rtti -ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib -Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare")
+# TODO work out a better way to pass start-group...
+# TODO put -Map arg somewhere more logical, make it depend on the app name
+set(CMAKE_EXE_LINKER_FLAGS_INIT ${CMAKE_EXE_LINKER_FLAGS} "-nostdlib -Wl,--gc-sections -Wl,--cref -Wl,--Map=linker.map -Wl,--start-group" CACHE STRING "Linker Flags")
diff --git a/tools/cmake/GetGitRevisionDescription.cmake b/tools/cmake/GetGitRevisionDescription.cmake
new file mode 100644
index 000000000..85eae1562
--- /dev/null
+++ b/tools/cmake/GetGitRevisionDescription.cmake
@@ -0,0 +1,130 @@
+# - Returns a version string from Git
+#
+# These functions force a re-configure on each git commit so that you can
+# trust the values of the variables in your build system.
+#
+#  get_git_head_revision(<refspecvar> <hashvar> [<additional arguments to git describe> ...])
+#
+# Returns the refspec and sha hash of the current head revision
+#
+#  git_describe(<var> [<additional arguments to git describe> ...])
+#
+# Returns the results of git describe on the source tree, and adjusting
+# the output so that it tests false if an error occurs.
+#
+#  git_get_exact_tag(<var> [<additional arguments to git describe> ...])
+#
+# Returns the results of git describe --exact-match on the source tree,
+# and adjusting the output so that it tests false if there was no exact
+# matching tag.
+#
+# Requires CMake 2.6 or newer (uses the 'function' command)
+#
+# Original Author:
+# 2009-2010 Ryan Pavlik <rpavlik@iastate.edu> <abiryan@ryand.net>
+# http://academic.cleardefinition.com
+# Iowa State University HCI Graduate Program/VRAC
+#
+# Copyright Iowa State University 2009-2010.
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+if(__get_git_revision_description)
+	return()
+endif()
+set(__get_git_revision_description YES)
+
+# We must run the following at "include" time, not at function call time,
+# to find the path to this module rather than the path to a calling list file
+get_filename_component(_gitdescmoddir ${CMAKE_CURRENT_LIST_FILE} PATH)
+
+function(get_git_head_revision _refspecvar _hashvar)
+	set(GIT_PARENT_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+	set(GIT_DIR "${GIT_PARENT_DIR}/.git")
+	while(NOT EXISTS "${GIT_DIR}")	# .git dir not found, search parent directories
+		set(GIT_PREVIOUS_PARENT "${GIT_PARENT_DIR}")
+		get_filename_component(GIT_PARENT_DIR ${GIT_PARENT_DIR} PATH)
+		if(GIT_PARENT_DIR STREQUAL GIT_PREVIOUS_PARENT)
+			# We have reached the root directory, we are not in git
+			set(${_refspecvar} "GITDIR-NOTFOUND" PARENT_SCOPE)
+			set(${_hashvar} "GITDIR-NOTFOUND" PARENT_SCOPE)
+			return()
+		endif()
+		set(GIT_DIR "${GIT_PARENT_DIR}/.git")
+	endwhile()
+	# check if this is a submodule
+	if(NOT IS_DIRECTORY ${GIT_DIR})
+		file(READ ${GIT_DIR} submodule)
+		string(REGEX REPLACE "gitdir: (.*)\n$" "\\1" GIT_DIR_RELATIVE ${submodule})
+		get_filename_component(SUBMODULE_DIR ${GIT_DIR} PATH)
+		get_filename_component(GIT_DIR ${SUBMODULE_DIR}/${GIT_DIR_RELATIVE} ABSOLUTE)
+	endif()
+	set(GIT_DATA "${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/git-data")
+	if(NOT EXISTS "${GIT_DATA}")
+		file(MAKE_DIRECTORY "${GIT_DATA}")
+	endif()
+
+	if(NOT EXISTS "${GIT_DIR}/HEAD")
+		return()
+	endif()
+	set(HEAD_FILE "${GIT_DATA}/HEAD")
+	configure_file("${GIT_DIR}/HEAD" "${HEAD_FILE}" COPYONLY)
+
+	configure_file("${_gitdescmoddir}/GetGitRevisionDescription.cmake.in"
+		"${GIT_DATA}/grabRef.cmake"
+		@ONLY)
+	include("${GIT_DATA}/grabRef.cmake")
+
+	set(${_refspecvar} "${HEAD_REF}" PARENT_SCOPE)
+	set(${_hashvar} "${HEAD_HASH}" PARENT_SCOPE)
+endfunction()
+
+function(git_describe _var)
+	if(NOT GIT_FOUND)
+		find_package(Git QUIET)
+	endif()
+	get_git_head_revision(refspec hash)
+	if(NOT GIT_FOUND)
+		set(${_var} "GIT-NOTFOUND" PARENT_SCOPE)
+		return()
+	endif()
+	if(NOT hash)
+		set(${_var} "HEAD-HASH-NOTFOUND" PARENT_SCOPE)
+		return()
+	endif()
+
+	# TODO sanitize
+	#if((${ARGN}" MATCHES "&&") OR
+	#	(ARGN MATCHES "||") OR
+	#	(ARGN MATCHES "\\;"))
+	#	message("Please report the following error to the project!")
+	#	message(FATAL_ERROR "Looks like someone's doing something nefarious with git_describe! Passed arguments ${ARGN}")
+	#endif()
+
+	#message(STATUS "Arguments to execute_process: ${ARGN}")
+
+	execute_process(COMMAND
+		"${GIT_EXECUTABLE}"
+		describe
+		${hash}
+		${ARGN}
+		WORKING_DIRECTORY
+		"${CMAKE_CURRENT_SOURCE_DIR}"
+		RESULT_VARIABLE
+		res
+		OUTPUT_VARIABLE
+		out
+		ERROR_QUIET
+		OUTPUT_STRIP_TRAILING_WHITESPACE)
+	if(NOT res EQUAL 0)
+		set(out "${out}-${res}-NOTFOUND")
+	endif()
+
+	set(${_var} "${out}" PARENT_SCOPE)
+endfunction()
+
+function(git_get_exact_tag _var)
+	git_describe(out --exact-match ${ARGN})
+	set(${_var} "${out}" PARENT_SCOPE)
+endfunction()
diff --git a/tools/cmake/GetGitRevisionDescription.cmake.in b/tools/cmake/GetGitRevisionDescription.cmake.in
new file mode 100644
index 000000000..6d8b708ef
--- /dev/null
+++ b/tools/cmake/GetGitRevisionDescription.cmake.in
@@ -0,0 +1,41 @@
+#
+# Internal file for GetGitRevisionDescription.cmake
+#
+# Requires CMake 2.6 or newer (uses the 'function' command)
+#
+# Original Author:
+# 2009-2010 Ryan Pavlik <rpavlik@iastate.edu> <abiryan@ryand.net>
+# http://academic.cleardefinition.com
+# Iowa State University HCI Graduate Program/VRAC
+#
+# Copyright Iowa State University 2009-2010.
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+set(HEAD_HASH)
+
+file(READ "@HEAD_FILE@" HEAD_CONTENTS LIMIT 1024)
+
+string(STRIP "${HEAD_CONTENTS}" HEAD_CONTENTS)
+if(HEAD_CONTENTS MATCHES "ref")
+	# named branch
+	string(REPLACE "ref: " "" HEAD_REF "${HEAD_CONTENTS}")
+	if(EXISTS "@GIT_DIR@/${HEAD_REF}")
+		configure_file("@GIT_DIR@/${HEAD_REF}" "@GIT_DATA@/head-ref" COPYONLY)
+	else()
+		configure_file("@GIT_DIR@/packed-refs" "@GIT_DATA@/packed-refs" COPYONLY)
+		file(READ "@GIT_DATA@/packed-refs" PACKED_REFS)
+		if(${PACKED_REFS} MATCHES "([0-9a-z]*) ${HEAD_REF}")
+			set(HEAD_HASH "${CMAKE_MATCH_1}")
+		endif()
+	endif()
+else()
+	# detached HEAD
+	configure_file("@GIT_DIR@/HEAD" "@GIT_DATA@/head-ref" COPYONLY)
+endif()
+
+if(NOT HEAD_HASH)
+	file(READ "@GIT_DATA@/head-ref" HEAD_HASH LIMIT 1024)
+	string(STRIP "${HEAD_HASH}" HEAD_HASH)
+endif()
diff --git a/tools/cmake/bootloader_subproject.cmake b/tools/cmake/bootloader_subproject.cmake
new file mode 100644
index 000000000..924a7ea77
--- /dev/null
+++ b/tools/cmake/bootloader_subproject.cmake
@@ -0,0 +1,13 @@
+# Glue to build the bootloader subproject binary as an external
+# cmake project under this one
+#
+#
+ExternalProject_Add(bootloader_subproject
+  # TODO: support overriding the bootloader in COMPONENT_PATHS
+  SOURCE_DIR ${IDF_PATH}/components/bootloader/subproject
+  BINARY_DIR ${CMAKE_BINARY_DIR}/bootloader_subproject
+  CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH=${IDF_PATH}
+  INSTALL_COMMAND ""
+  )
+
+
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
new file mode 100644
index 000000000..540caadf9
--- /dev/null
+++ b/tools/cmake/components.cmake
@@ -0,0 +1,133 @@
+# Search 'component_dirs' for components and return them
+# as a list of names in 'component_names' and a list of full paths in
+# 'component_paths'
+#
+# component_paths contains only unique component names. Directories
+# earlier in the component_dirs list take precedence.
+function(find_all_components component_dirs filter_names component_paths component_names)
+  # component_dirs entries can be files or lists of files
+  set(paths "")
+  set(names "")
+
+  # start by expanding the component_dirs list with all subdirectories
+  foreach(dir ${component_dirs})
+    # Iterate any subdirectories for values
+    file(GLOB subdirs LIST_DIRECTORIES true "${dir}/*")
+    foreach(subdir ${subdirs})
+      set(component_dirs "${component_dirs};${subdir}")
+    endforeach()
+  endforeach()
+
+  # Look for a component in each component_dirs entry
+  foreach(dir ${component_dirs})
+    file(GLOB component "${dir}/CMakeLists.txt")
+    if(component)
+      get_filename_component(component "${component}" DIRECTORY)
+      get_filename_component(name "${component}" NAME)
+      if(NOT filter_names OR (name IN_LIST filter_names))
+        if(NOT name IN_LIST names)
+          set(names "${names};${name}")
+          set(paths "${paths};${component}")
+        endif()
+      endif()
+
+    else()  # no CMakeLists.txt file
+      # test for legacy component.mk and warn
+      file(GLOB legacy_component "${dir}/component.mk")
+      if(legacy_component)
+        get_filename_component(legacy_component "${legacy_component}" DIRECTORY)
+        message(WARNING "Component ${legacy_component} contains old-style component.mk but no CMakeLists.txt. Component will be skipped.")
+      endif()
+    endif(component)
+
+  endforeach(dir ${component_dirs})
+
+  set(${component_paths} ${paths} PARENT_SCOPE)
+  set(${component_names} ${names} PARENT_SCOPE)
+endfunction()
+
+
+# Add a component to the build, using the COMPONENT variables defined
+# in the parent
+#
+function(register_component)
+  get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
+  get_filename_component(component ${component_dir} NAME)
+
+  if(NOT COMPONENT_SRCDIRS)
+    set(COMPONENT_SRCDIRS ".")
+  endif()
+  spaces2list(COMPONENT_SRCDIRS)
+
+  if(NOT COMPONENT_ADD_INCLUDEDIRS)
+    set(COMPONENT_ADD_INCLUDEDIRS "include")
+  endif()
+  spaces2list(COMPONENT_ADD_INCLUDEDIRS)
+
+  # if not explicit, build COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
+  if(NOT COMPONENT_SRCS)
+    foreach(dir ${COMPONENT_SRCDIRS})
+      get_filename_component(dir ${dir} ABSOLUTE BASE_DIR ${component_dir})
+      file(GLOB matches "${dir}/*.[c|S]" "${dir}/*.cpp")
+      if(matches)
+        list(SORT matches)
+        set(COMPONENT_SRCS "${COMPONENT_SRCS};${matches}")
+      endif(matches)
+    endforeach()
+  endif()
+
+  # add public includes from other components when building this component
+  if(COMPONENT_SRCS)
+    add_library(${component} STATIC ${COMPONENT_SRCS})
+    set(include_type PUBLIC)
+  else()
+    add_library(${component} INTERFACE) # header-only component
+    set(include_type INTERFACE)
+  endif(COMPONENT_SRCS)
+
+  foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
+    get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+    target_include_directories(${component} ${include_type} ${include_dir})
+  endforeach()
+
+  foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
+    if (${include_type} STREQUAL INTERFACE)
+      message(FATAL_ERROR "Component ${component} can't have no source files and COMPONENT_PRIV_INCLUDEDIRS set.")
+    endif()
+    get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+    target_include_directories(${component} PRIVATE ${include_dir})
+  endforeach()
+
+endfunction()
+
+function(register_config_only_component)
+  get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
+  get_filename_component(component ${component_dir} NAME)
+
+  # No-op for now...
+endfunction()
+
+function(finish_component_registration)
+  # each component should see the include directories of each other
+  #
+  # (we can't do this until all components are registered, because if(TARGET ...) won't work
+  foreach(a ${COMPONENTS})
+    if (TARGET ${a})
+      get_target_property(a_type ${a} TYPE)
+      if (${a_type} STREQUAL STATIC_LIBRARY)
+        foreach(b ${COMPONENTS})
+          if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
+            target_include_directories(${a} PRIVATE
+              $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>
+              )
+          endif()
+        endforeach(b)
+      endif(${a_type} STREQUAL STATIC_LIBRARY)
+
+      set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
+    endif()
+  endforeach()
+
+  # set COMPONENT_LIBRARIES in top-level scope
+  set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES}" PARENT_SCOPE)
+endfunction()
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
new file mode 100644
index 000000000..2c7e68ede
--- /dev/null
+++ b/tools/cmake/kconfig.cmake
@@ -0,0 +1,82 @@
+include(ExternalProject)
+
+add_compile_options("-I${CMAKE_BINARY_DIR}")
+
+set(MCONF ${IDF_PATH}/tools/kconfig/mconf)
+
+set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
+set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
+set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
+
+set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
+
+# Use the existing Makefile to build mconf when needed
+#
+# TODO: replace this with something more Windows-friendly
+ExternalProject_Add(mconf
+  SOURCE_DIR ${IDF_PATH}/tools/kconfig
+  CONFIGURE_COMMAND ""
+  BUILD_IN_SOURCE 1
+  BUILD_COMMAND make mconf
+  BUILD_BYPRODUCTS ${MCONF}
+  INSTALL_COMMAND ""
+  EXCLUDE_FROM_ALL 1
+  )
+
+# Find all Kconfig files for all components
+function(build_component_config)
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
+  set(kconfigs )
+  set(kconfigs_projbuild )
+
+  # Find Kconfig and Kconfig.projbuild for each component as applicable
+  # if any of these change, cmake should rerun
+  foreach(dir ${COMPONENT_PATHS})
+    file(GLOB kconfig "${dir}/Kconfig")
+    if(kconfig)
+      set(kconfigs "${kconfigs} ${kconfig}")
+      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+    endif()
+    file(GLOB kconfig ${dir}/Kconfig.projbuild)
+    if(kconfig)
+      set(kconfigs_projbuild "${kconfigs_projbuild} ${kconfig}")
+      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+    endif()
+  endforeach(dir ${COMPONENT_PATHS})
+
+  # Generate the menuconfig target (uses C-based mconf tool)
+  add_custom_target(menuconfig
+    DEPENDS mconf
+    COMMAND ${CMAKE_COMMAND} -E env
+                "COMPONENT_KCONFIGS=${kconfigs}"
+                "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+                "KCONFIG_CONFIG=${SDKCONFIG}"
+                ${IDF_PATH}/tools/kconfig/mconf ${ROOT_KCONFIG}
+    VERBATIM
+    USES_TERMINAL)
+
+  # Generate configuration output via confgen.py
+  # makes sdkconfig.h and skdconfig.cmake
+  #
+  # This happens at cmake runtime not during the build
+  execute_process(COMMAND python ${IDF_PATH}/tools/kconfig_new/confgen.py
+    --kconfig ${ROOT_KCONFIG}
+    --config ${SDKCONFIG}
+    --env "COMPONENT_KCONFIGS=${kconfigs}"
+    --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+    --output header ${SDKCONFIG_HEADER}
+    --output cmake ${SDKCONFIG_CMAKE})
+
+  # When sdkconfig file changes in the future, trigger a cmake run
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG})
+
+  # Ditto if either of the generated files are missing/modified (this is a bit irritating as it means
+  # you can't edit these manually without them being regenerated, but I don't know of a better way...)
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG_HEADER})
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG_CMAKE})
+
+  # Or if the config generation tool changes
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${IDF_PATH}/tools/kconfig_new/confgen.py)
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${IDF_PATH}/tools/kconfig_new/kconfiglib.py)
+
+endfunction()
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
new file mode 100644
index 000000000..29eb78aad
--- /dev/null
+++ b/tools/cmake/utilities.cmake
@@ -0,0 +1,60 @@
+# set_default
+#
+# Define a variable to a default value if otherwise unset.
+#
+# Priority for new value is:
+# - Existing cmake value (ie set with cmake -D, or already set in CMakeLists)
+# - Value of any non-empty environment variable of the same name
+# - Default value as provided to function
+#
+function(set_default variable default_value)
+  if(NOT ${variable})
+    if($ENV{${variable}})
+      set(${variable} $ENV{${variable}} PARENT_SCOPE)
+    else()
+      set(${variable} ${default_value} PARENT_SCOPE)
+    endif()
+  endif()
+endfunction()
+
+# spaces2list
+#
+# Take a variable whose value was space-delimited values, convert to a cmake
+# list (semicolon-delimited)
+#
+# Note: if using this for directories, keeps the issue in place that
+# directories can't contain spaces...
+function(spaces2list variable_name)
+  string(REPLACE " " ";" tmp "${${variable_name}}")
+  set("${variable_name}" "${tmp}" PARENT_SCOPE)
+endfunction()
+
+# move_if_different
+#
+# If 'source' has different md5sum to 'destination' (or destination
+# does not exist, move it across.
+#
+# If 'source' has the same md5sum as 'destination', delete 'source'.
+#
+# Avoids timestamp updates for re-generated files where content hasn't
+# changed.
+function(move_if_different source destination)
+  set(do_copy 1)
+  file(GLOB dest_exists ${destination})
+  if(dest_exists)
+    file(MD5 ${source} source_md5)
+    file(MD5 ${destination} dest_md5)
+    if(source_md5 STREQUAL dest_md5)
+      set(do_copy "")
+    endif()
+  endif()
+
+  if(do_copy)
+    message("Moving ${source} -> ${destination}")
+    file(RENAME ${source} ${destination})
+  else()
+    message("Not moving ${source} -> ${destination}")
+    file(REMOVE ${source})
+  endif()
+
+endfunction()

From 99a2359c5c725796a660d3891383a146fe391bc7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 15 Jan 2018 09:55:00 +1100
Subject: [PATCH 003/112] confgen: Create config file if missing

---
 tools/cmake/kconfig.cmake    |  1 +
 tools/kconfig_new/confgen.py | 27 ++++++++++++++++++++++++---
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 2c7e68ede..6fd68de14 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -62,6 +62,7 @@ function(build_component_config)
   execute_process(COMMAND python ${IDF_PATH}/tools/kconfig_new/confgen.py
     --kconfig ${ROOT_KCONFIG}
     --config ${SDKCONFIG}
+    --create-config-if-missing
     --env "COMPONENT_KCONFIGS=${kconfigs}"
     --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
     --output header ${SDKCONFIG_HEADER}
diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
index afca4176d..ca5ee6390 100755
--- a/tools/kconfig_new/confgen.py
+++ b/tools/kconfig_new/confgen.py
@@ -39,13 +39,18 @@ def main():
                         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'))
+                        metavar=('FORMAT', 'FILENAME'),
+                        default=[])
 
     parser.add_argument('--env', action='append', default=[],
                         help='Environment to set when evaluating the config file', metavar='NAME=VAL')
@@ -69,7 +74,13 @@ def main():
     config = kconfiglib.Kconfig(args.kconfig)
 
     if args.config is not None:
-        config.load_config(args.config)
+        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)
+        else:
+            raise RuntimeError("Config file not found: %s" % args.config)
 
         for output_type, filename in args.output:
             temp_file = tempfile.mktemp(prefix="confgen_tmp")
@@ -146,5 +157,15 @@ OUTPUT_FORMATS = {
     "cmake" : write_cmake,
     "docs" : gen_kconfig_doc.write_docs }
 
+class FatalError(RuntimeError):
+    """
+    Class for runtime errors (not caused by bugs but by user input).
+    """
+    pass
+
 if __name__ == '__main__':
-    main()
+    try:
+        main()
+    except FatalError as e:
+        print("A fatal error occurred: %s" % e)
+        sys.exit(2)

From 35f521afb63cf4210afb13821455be80afb829b9 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 15 Jan 2018 10:25:35 +1100
Subject: [PATCH 004/112] cmake: Add toolchain version check

---
 idf.cmake                                 |  8 ++++++
 tools/cmake/crosstool_version_check.cmake | 31 +++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 tools/cmake/crosstool_version_check.cmake

diff --git a/idf.cmake b/idf.cmake
index 8586d687a..d1623f275 100644
--- a/idf.cmake
+++ b/idf.cmake
@@ -32,6 +32,13 @@ include(GetGitRevisionDescription)
 include(utilities)
 include(components)
 include(kconfig)
+include(crosstool_version_check)
+
+#
+# Warn if the toolchain version doesn't match
+#
+gcc_version_check("5.2.0")
+crosstool_version_check("1.22.0-80-g6c4433a")
 
 #
 # Configure optional variables
@@ -76,3 +83,4 @@ finish_component_registration()
 if(NOT BOOTLOADER_BUILD)
   include(bootloader_subproject)
 endif()
+
diff --git a/tools/cmake/crosstool_version_check.cmake b/tools/cmake/crosstool_version_check.cmake
new file mode 100644
index 000000000..ed518907e
--- /dev/null
+++ b/tools/cmake/crosstool_version_check.cmake
@@ -0,0 +1,31 @@
+# Function to check the toolchain used the expected version
+# of crosstool, and warn otherwise
+
+set(ctng_version_warning "Check Getting Started documentation or proceed at own risk.")
+
+function(gcc_version_check expected_gcc_version)
+  if(NOT "${CMAKE_C_COMPILER_VERSION}" STREQUAL "${expected_gcc_version}")
+    message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} version ${CMAKE_C_COMPILER_VERSION} is not the supported version ${expected_gcc_version}. ${ctng_version_warning}")
+  endif()
+endfunction()
+
+function(crosstool_version_check expected_ctng_version)
+  execute_process(
+    COMMAND ${CMAKE_C_COMPILER} -v
+    ERROR_VARIABLE toolchain_stderr
+    OUTPUT_QUIET)
+
+    string(REGEX MATCH "crosstool-ng-[0-9a-g\\.-]+" ctng_version "${toolchain_stderr}")
+    string(REPLACE "crosstool-ng-" "" ctng_version "${ctng_version}")
+	# We use FIND to match version instead of STREQUAL because some toolchains are built
+	# with longer git hash strings than others. This will match any version which starts with
+	# the expected version string.
+	string(FIND "${ctng_version}" "${expected_ctng_version}" found_expected_version)
+    if(NOT ctng_version)
+        message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} does not appear to be built with crosstool-ng. "
+            "${ctng_version_warning}")
+    elseif(found_expected_version EQUAL -1)
+        message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} crosstool-ng version ${ctng_version} "
+            "doesn't match supported version ${expected_ctng_version}. ${ctng_version_warning}")
+    endif()
+endfunction()

From 68e75dd0df57d33b1471ef806b18234335db5e86 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 15 Jan 2018 13:20:38 +1100
Subject: [PATCH 005/112] cmake: Detect missing or out of date submodules
 during cmake pass

---
 components/aws_iot/CMakeLists.txt   |  1 -
 components/coap/CMakeLists.txt      |  2 --
 components/libsodium/CMakeLists.txt |  2 --
 components/micro-ecc/CMakeLists.txt |  2 --
 components/nghttp/CMakeLists.txt    |  1 -
 components/spiffs/CMakeLists.txt    |  1 -
 idf.cmake                           |  4 ++-
 tools/cmake/git_submodules.cmake    | 51 +++++++++++++++++++++++++++++
 tools/cmake/utilities.cmake         | 14 ++++++++
 9 files changed, 68 insertions(+), 10 deletions(-)
 create mode 100644 tools/cmake/git_submodules.cmake

diff --git a/components/aws_iot/CMakeLists.txt b/components/aws_iot/CMakeLists.txt
index 29909bd14..50219ab09 100644
--- a/components/aws_iot/CMakeLists.txt
+++ b/components/aws_iot/CMakeLists.txt
@@ -2,7 +2,6 @@ if(CONFIG_AWS_IOT_SDK)
 
 set(COMPONENT_ADD_INCLUDEDIRS "include aws-iot-device-sdk-embedded-C/include")
 set(COMPONENT_SRCDIRS "aws-iot-device-sdk-embedded-C/src port")
-set(COMPONENT_SUBMODULES aws-iot-device-sdk-embedded-C)
 
 register_component()
 
diff --git a/components/coap/CMakeLists.txt b/components/coap/CMakeLists.txt
index 9a9b65ccb..2f51d6c0a 100644
--- a/components/coap/CMakeLists.txt
+++ b/components/coap/CMakeLists.txt
@@ -19,8 +19,6 @@ set(COMPONENT_SRCS
   port/coap_io_socket.c
   )
 
-set(COMPONENT_SUBMODULES libcoap)
-
 register_component()
 
 # Needed for coap headers in public builds, also.
diff --git a/components/libsodium/CMakeLists.txt b/components/libsodium/CMakeLists.txt
index 78ab23c64..f45025084 100644
--- a/components/libsodium/CMakeLists.txt
+++ b/components/libsodium/CMakeLists.txt
@@ -1,7 +1,5 @@
 set(SRC libsodium/src/libsodium)
 
-set(COMPONENT_SUBMODULES libsodium)
-
 set(COMPONENT_SRCDIRS
   port
 
diff --git a/components/micro-ecc/CMakeLists.txt b/components/micro-ecc/CMakeLists.txt
index 6ae9c8ae3..13bc9cfb6 100644
--- a/components/micro-ecc/CMakeLists.txt
+++ b/components/micro-ecc/CMakeLists.txt
@@ -3,6 +3,4 @@ set(COMPONENT_SRCS micro-ecc/uECC.c)
 
 set(COMPONENT_ADD_INCLUDEDIRS micro-ecc)
 
-set(COMPONENT_SUBMODULES micro-ecc)
-
 register_component()
diff --git a/components/nghttp/CMakeLists.txt b/components/nghttp/CMakeLists.txt
index 1a549b075..c7e4b754b 100644
--- a/components/nghttp/CMakeLists.txt
+++ b/components/nghttp/CMakeLists.txt
@@ -1,5 +1,4 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include nghttp2/lib/includes)
 set(COMPONENT_SRCDIRS nghttp2/lib port)
-set(COMPONENT_SUBMODULES nghttp2)
 
 register_component()
diff --git a/components/spiffs/CMakeLists.txt b/components/spiffs/CMakeLists.txt
index 0435a38b6..5e0027f52 100644
--- a/components/spiffs/CMakeLists.txt
+++ b/components/spiffs/CMakeLists.txt
@@ -1,6 +1,5 @@
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS "spiffs/src")
 set(COMPONENT_SRCDIRS ". spiffs/src")
-set(COMPONENT_SUBMODULES "spiffs")
 register_component()
 
diff --git a/idf.cmake b/idf.cmake
index d1623f275..800f32a0f 100644
--- a/idf.cmake
+++ b/idf.cmake
@@ -33,6 +33,7 @@ include(utilities)
 include(components)
 include(kconfig)
 include(crosstool_version_check)
+include(git_submodules)
 
 #
 # Warn if the toolchain version doesn't match
@@ -50,8 +51,8 @@ set_default(EXTRA_COMPONENT_DIRS "")
 set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
 spaces2list(COMPONENT_DIRS)
 
-# expand COMPONENT_DIRS variable into full paths to all components and their names
 spaces2list(COMPONENTS)
+# Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
 find_all_components("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
 build_component_config()
 
@@ -66,6 +67,7 @@ add_definitions(-DHAVE_CONFIG_H)
 
 git_describe(GIT_REVISION)
 add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
+git_submodule_check("${IDF_PATH}")
 
 add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
diff --git a/tools/cmake/git_submodules.cmake b/tools/cmake/git_submodules.cmake
new file mode 100644
index 000000000..be71f41f6
--- /dev/null
+++ b/tools/cmake/git_submodules.cmake
@@ -0,0 +1,51 @@
+find_package(Git)
+
+if(NOT GIT_FOUND)
+  message(WARNING "Git executable was not found. Git submodule checks will not be executed. If you have any build issues at all, start by adding git executable to the PATH and rerun cmake to not see this warning again.")
+
+  function(git_submodule_check root_path)
+    # no-op
+  endfunction()
+else(NOT GIT_FOUND)
+
+  function(git_submodule_check root_path)
+
+    execute_process(
+      COMMAND ${GIT_EXECUTABLE} submodule status
+      WORKING_DIRECTORY ${root_path}
+      OUTPUT_VARIABLE submodule_status
+      )
+
+    # git submodule status output not guaranteed to be stable,
+    # may need to check GIT_VERSION_STRING and do some fiddling in the
+    # future...
+
+    lines2list(submodule_status)
+
+    foreach(line ${submodule_status})
+      string(REGEX MATCH "(.)[0-9a-f]+ ([^\( ]+) ?" _ignored "${line}")
+      set(status "${CMAKE_MATCH_1}")
+      set(submodule_path "${CMAKE_MATCH_2}")
+
+      if("${status}" STREQUAL "-")  # missing submodule
+        message(STATUS "Initialising new submodule ${submodule_path}...")
+        execute_process(
+          COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive ${submodule_path}
+          WORKING_DIRECTORY ${root_path}
+          RESULT_VARIABLE git_result
+          )
+        if(git_result)
+          message(FATAL_ERROR "Git submodule init failed for ${submodule_path}")
+        endif(git_result)
+
+      elseif(NOT "${status}" STREQUAL " ")
+        message(WARNING "Git submodule ${submodule_path} is out of date. Run 'git submodule update --init --recursive' to fix.")
+      endif()
+    endforeach()
+  endfunction(git_submodule_check)
+
+endif(NOT GIT_FOUND)
+
+
+
+
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 29eb78aad..962d46c25 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -24,11 +24,25 @@ endfunction()
 #
 # Note: if using this for directories, keeps the issue in place that
 # directories can't contain spaces...
+#
+# TODO: look at cmake separate_arguments, which is quote-aware
 function(spaces2list variable_name)
   string(REPLACE " " ";" tmp "${${variable_name}}")
   set("${variable_name}" "${tmp}" PARENT_SCOPE)
 endfunction()
 
+
+# lines2list
+#
+# Take a variable with multiple lines of output in it, convert it
+# to a cmake list (semicolon-delimited), one line per item
+#
+function(lines2list variable_name)
+  string(REGEX REPLACE "\r?\n" ";" tmp "${${variable_name}}")
+  set("${variable_name}" "${tmp}" PARENT_SCOPE)
+endfunction()
+
+
 # move_if_different
 #
 # If 'source' has different md5sum to 'destination' (or destination

From f04525095f46a3118439cb1bea15145c1f4daede Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 15 Jan 2018 13:22:02 +1100
Subject: [PATCH 006/112] cmake: Move third-party cmake modules to their own
 directory

---
 idf.cmake                                                       | 2 +-
 tools/cmake/{ => third_party}/GetGitRevisionDescription.cmake   | 0
 .../cmake/{ => third_party}/GetGitRevisionDescription.cmake.in  | 0
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename tools/cmake/{ => third_party}/GetGitRevisionDescription.cmake (100%)
 rename tools/cmake/{ => third_party}/GetGitRevisionDescription.cmake.in (100%)

diff --git a/idf.cmake b/idf.cmake
index 800f32a0f..225b229e0 100644
--- a/idf.cmake
+++ b/idf.cmake
@@ -27,7 +27,7 @@ set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
 #
 # Load cmake modules
 #
-set(CMAKE_MODULE_PATH "${IDF_PATH}/tools/cmake" ${CMAKE_MODULE_PATH})
+set(CMAKE_MODULE_PATH "${IDF_PATH}/tools/cmake" "${IDF_PATH}/tools/cmake/third_party" ${CMAKE_MODULE_PATH})
 include(GetGitRevisionDescription)
 include(utilities)
 include(components)
diff --git a/tools/cmake/GetGitRevisionDescription.cmake b/tools/cmake/third_party/GetGitRevisionDescription.cmake
similarity index 100%
rename from tools/cmake/GetGitRevisionDescription.cmake
rename to tools/cmake/third_party/GetGitRevisionDescription.cmake
diff --git a/tools/cmake/GetGitRevisionDescription.cmake.in b/tools/cmake/third_party/GetGitRevisionDescription.cmake.in
similarity index 100%
rename from tools/cmake/GetGitRevisionDescription.cmake.in
rename to tools/cmake/third_party/GetGitRevisionDescription.cmake.in

From 067a19ad885af655faadde21187b7449dfc165b9 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 16 Jan 2018 11:16:14 +1100
Subject: [PATCH 007/112] cmake: Move global IDF-specific compiler/linker
 options out of the toolchain file

Should restore compatibility with cmake pre-v3.7
---
 idf.cmake                       |  5 +--
 toolchain.cmake                 |  6 +--
 tools/cmake/idf_functions.cmake | 67 +++++++++++++++++++++++++++++++++
 tools/cmake/utilities.cmake     | 22 +++++++++++
 4 files changed, 92 insertions(+), 8 deletions(-)
 create mode 100644 tools/cmake/idf_functions.cmake

diff --git a/idf.cmake b/idf.cmake
index 225b229e0..c6cb99d7a 100644
--- a/idf.cmake
+++ b/idf.cmake
@@ -34,6 +34,7 @@ include(components)
 include(kconfig)
 include(crosstool_version_check)
 include(git_submodules)
+include(idf_functions)
 
 #
 # Warn if the toolchain version doesn't match
@@ -61,9 +62,7 @@ include(${SDKCONFIG_CMAKE})
 
 #
 # Add some idf-wide definitions
-#
-add_definitions(-DESP_PLATFORM)
-add_definitions(-DHAVE_CONFIG_H)
+idf_set_global_compiler_options()
 
 git_describe(GIT_REVISION)
 add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
diff --git a/toolchain.cmake b/toolchain.cmake
index 12e3f5a5a..cecba78af 100644
--- a/toolchain.cmake
+++ b/toolchain.cmake
@@ -4,8 +4,4 @@ set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
 set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
 set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
 
-set(CMAKE_C_FLAGS_INIT "-Og -ggdb -std=gnu99 -ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib -Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare -Wno-old-style-declaration")
-set(CMAKE_CXX_FLAGS_INIT "-Og -ggdb -std=gnu++11 -fno-exceptions -fno-rtti -ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib -Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare")
-# TODO work out a better way to pass start-group...
-# TODO put -Map arg somewhere more logical, make it depend on the app name
-set(CMAKE_EXE_LINKER_FLAGS_INIT ${CMAKE_EXE_LINKER_FLAGS} "-nostdlib -Wl,--gc-sections -Wl,--cref -Wl,--Map=linker.map -Wl,--start-group" CACHE STRING "Linker Flags")
+set(CMAKE_EXE_LINKER_FLAGS "-nostdlib" CACHE STRING "Linker Base Flags")
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
new file mode 100644
index 000000000..72216dfbf
--- /dev/null
+++ b/tools/cmake/idf_functions.cmake
@@ -0,0 +1,67 @@
+# Some IDF-specific functions and functions
+
+
+# Add all the IDF global compiler & preprocessor options
+# (applied to all components). Some are config-dependent
+#
+# If you only want to set options for a particular component,
+# don't call or edit this function. TODO DESCRIBE WHAT TO DO INSTEAD
+#
+function(idf_set_global_compiler_options)
+  add_definitions(-DESP_PLATFORM)
+  add_definitions(-DHAVE_CONFIG_H)
+
+  if(CONFIG_OPTIMIZATION_LEVEL_RELEASE)
+    add_compile_options(-Os)
+  else()
+    add_compile_options(-Og)
+  endif()
+
+  add_c_compile_options(-std=gnu99)
+
+  add_cxx_compile_options(-std=gnu++11 -fno-rtti)
+
+  if(CONFIG_CXX_EXCEPTIONS)
+    add_cxx_compile_options(-fexceptions)
+  else()
+    add_cxx_compile_options(-fno-exceptions)
+  endif()
+
+  # Default compiler configuration
+  add_compile_options(-ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib)
+
+  # Default warnings configuration
+  add_compile_options(-Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare)
+  add_c_compile_options(-Wno-old-style-declaration)
+
+  # Stack protection
+  if(NOT BOOTLOADER_BUILD)
+    if(CONFIG_STACK_CHECK_NORM)
+      add_compile_options(-fstack-protector)
+    elseif(CONFIG_STACK_CHECK_STRONG)
+      add_compile_options(-fstack-protector-strong)
+    elseif(CONFIG_STACK_CHECK_ALL)
+      add_compile_options(-fstack-protector-all)
+    endif()
+  endif()
+
+  if(CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED)
+    add_definitions(-DNDEBUG)
+  endif()
+
+  # Always generate debug symbols (even in Release mode, these don't
+  # go itno ther final binary
+  add_compile_options(-ggdb)
+
+endfunction()
+
+# Override add_executable to add IDF-specific
+# linker flags & map file to all built executables
+function(add_executable target)
+  get_filename_component(basename ${target} NAME_WE)
+  set(mapfile "${basename}.map")
+
+  _add_executable(${ARGV})
+
+  target_link_libraries(${target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
+endfunction()
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 962d46c25..ce71f5ced 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -72,3 +72,25 @@ function(move_if_different source destination)
   endif()
 
 endfunction()
+
+# add_compile_options variant for C++ code only
+#
+# This adds global options, set target properties for
+# component-specific flags
+function(add_cxx_compile_options)
+  foreach(option ${ARGV})
+    # note: the Visual Studio Generator doesn't support this...
+    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:${option}>)
+  endforeach()
+endfunction()
+
+# add_compile_options variant for C code only
+#
+# This adds global options, set target properties for
+# component-specific flags
+function(add_c_compile_options)
+  foreach(option ${ARGV})
+    # note: the Visual Studio Generator doesn't support this...
+    add_compile_options($<$<COMPILE_LANGUAGE:C>:${option}>)
+  endforeach()
+endfunction()

From 7f29593a7dd95db0005203c347b46234d7ed1ec7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 16 Jan 2018 16:50:15 +1100
Subject: [PATCH 008/112] cmake: Bootloader subproject & "clean" cleanup

---
 idf.cmake                               |  3 ++-
 tools/cmake/bootloader_subproject.cmake | 26 +++++++++++++++++++------
 tools/cmake/idf_functions.cmake         |  2 ++
 3 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/idf.cmake b/idf.cmake
index c6cb99d7a..efb4631d2 100644
--- a/idf.cmake
+++ b/idf.cmake
@@ -12,11 +12,12 @@ if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES
     "re-running cmake.")
 endif()
 
-set(IDF_PATH $ENV{IDF_PATH})
+set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
   # Documentation says you should set IDF_PATH in your environment, but we
   # can infer it here if it's not set.
   set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
+  set($ENV{IDF_PATH} "${IDF_PATH}")
 endif()
 
 # PROJECT_PATH has the path to the IDF project (top-level cmake directory)
diff --git a/tools/cmake/bootloader_subproject.cmake b/tools/cmake/bootloader_subproject.cmake
index 924a7ea77..c141fadd3 100644
--- a/tools/cmake/bootloader_subproject.cmake
+++ b/tools/cmake/bootloader_subproject.cmake
@@ -2,12 +2,26 @@
 # cmake project under this one
 #
 #
-ExternalProject_Add(bootloader_subproject
-  # TODO: support overriding the bootloader in COMPONENT_PATHS
-  SOURCE_DIR ${IDF_PATH}/components/bootloader/subproject
-  BINARY_DIR ${CMAKE_BINARY_DIR}/bootloader_subproject
-  CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH=${IDF_PATH}
-  INSTALL_COMMAND ""
+set(bootloader_subproject_build_dir "${CMAKE_BINARY_DIR}/bootloader_subproject")
+set(bootloader_binary_files
+  "${bootloader_subproject_build_dir}/bootloader.elf"
+  "${bootloader_subproject_build_dir}/bootloader.bin"
+  "${bootloader_subproject_build_dir}/bootloader.map"
   )
 
+ExternalProject_Add(bootloader_subproject
+  # TODO: support overriding the bootloader in COMPONENT_PATHS
+  SOURCE_DIR "${IDF_PATH}/components/bootloader/subproject"
+  BINARY_DIR "${bootloader_subproject_build_dir}"
+  CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH="${IDF_PATH}"
+  INSTALL_COMMAND ""
+  BUILD_ALWAYS 1  # no easy way around this...
+  BUILD_BYPRODUCTS ${bootloader_binary_files}
+  )
 
+# this is a hack due to an (annoying) shortcoming in cmake, it can't
+# extend the 'clean' target to the external project
+# see thread: https://cmake.org/pipermail/cmake/2016-December/064660.html
+#
+# So for now we just have the top-level build remove the final build products...
+set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${bootloader_binary_files})
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 72216dfbf..6da978038 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -64,4 +64,6 @@ function(add_executable target)
   _add_executable(${ARGV})
 
   target_link_libraries(${target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
+
+  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
 endfunction()

From 134f2238bd1a45cc2cf3fce4f10ab640d305f6e7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 17 Jan 2018 14:01:57 +1100
Subject: [PATCH 009/112] cmake: Refactor main cmake project logic

---
 .../bootloader/subproject/CMakeLists.txt      |  2 +-
 .../get-started/hello_world/CMakeLists.txt    |  2 +-
 tools/cmake/components.cmake                  | 12 ++---
 tools/cmake/idf_functions.cmake               | 47 ++++++++++++++++-
 tools/cmake/kconfig.cmake                     | 16 +++---
 idf.cmake => tools/cmake/project.cmake        | 50 +++++--------------
 6 files changed, 74 insertions(+), 55 deletions(-)
 rename idf.cmake => tools/cmake/project.cmake (52%)

diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index e8f920f2e..ab7b5aaa6 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -12,7 +12,7 @@ if(NOT SDKCONFIG)
   message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the app build process.")
 endif()
 
-include($ENV{IDF_PATH}/idf.cmake)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
 add_executable(bootloader.elf
   main/bootloader_start.c
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
index 62a03947f..4e66c5efd 100644
--- a/examples/get-started/hello_world/CMakeLists.txt
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -4,7 +4,7 @@ cmake_minimum_required(VERSION 3.5)
 set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
 project(idf_project ASM C CXX)
 
-include($ENV{IDF_PATH}/idf.cmake)
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
 add_executable(hello_world.elf
   main/hello_world_main.c)
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 540caadf9..3a9e1fc2f 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -4,7 +4,7 @@
 #
 # component_paths contains only unique component names. Directories
 # earlier in the component_dirs list take precedence.
-function(find_all_components component_dirs filter_names component_paths component_names)
+function(components_find_all component_dirs filter_names component_paths component_names)
   # component_dirs entries can be files or lists of files
   set(paths "")
   set(names "")
@@ -44,7 +44,7 @@ function(find_all_components component_dirs filter_names component_paths compone
 
   set(${component_paths} ${paths} PARENT_SCOPE)
   set(${component_names} ${names} PARENT_SCOPE)
-endfunction()
+endfunction(components_find_all)
 
 
 # Add a component to the build, using the COMPONENT variables defined
@@ -98,16 +98,16 @@ function(register_component)
     target_include_directories(${component} PRIVATE ${include_dir})
   endforeach()
 
-endfunction()
+endfunction(register_component)
 
 function(register_config_only_component)
   get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
   get_filename_component(component ${component_dir} NAME)
 
   # No-op for now...
-endfunction()
+endfunction(register_config_only_component)
 
-function(finish_component_registration)
+function(components_finish_registration)
   # each component should see the include directories of each other
   #
   # (we can't do this until all components are registered, because if(TARGET ...) won't work
@@ -130,4 +130,4 @@ function(finish_component_registration)
 
   # set COMPONENT_LIBRARIES in top-level scope
   set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES}" PARENT_SCOPE)
-endfunction()
+endfunction(components_finish_registration)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 6da978038..34785b102 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -1,5 +1,24 @@
 # Some IDF-specific functions and functions
 
+include(crosstool_version_check)
+
+macro(idf_set_global_variables)
+
+  set_default(EXTRA_COMPONENT_DIRS "")
+
+  # PROJECT_PATH has the path to the IDF project (top-level cmake directory)
+  #
+  # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
+  set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
+
+  # Note: "main" is no longer a component...
+  #
+  set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
+  spaces2list(COMPONENT_DIRS)
+
+  spaces2list(COMPONENTS)
+
+endmacro()
 
 # Add all the IDF global compiler & preprocessor options
 # (applied to all components). Some are config-dependent
@@ -53,7 +72,9 @@ function(idf_set_global_compiler_options)
   # go itno ther final binary
   add_compile_options(-ggdb)
 
-endfunction()
+  add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
+
+endfunction(idf_set_global_compiler_options)
 
 # Override add_executable to add IDF-specific
 # linker flags & map file to all built executables
@@ -66,4 +87,26 @@ function(add_executable target)
   target_link_libraries(${target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
 
   set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
-endfunction()
+endfunction(add_executable)
+
+
+# Verify the IDF environment is configured correctly (environment, toolchain, etc)
+function(idf_verify_environment)
+
+  # Check toolchain is configured properly in cmake
+  if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
+    message(FATAL_ERROR "The parent project CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
+      "before including this file. "
+      "Update CMakeLists.txt to match the template project and delete CMakeCache.txt before "
+      "re-running cmake.")
+  endif()
+
+  #
+  # Warn if the toolchain version doesn't match
+  #
+  gcc_version_check("5.2.0")
+  crosstool_version_check("1.22.0-80-g6c4433a")
+
+  
+
+endfunction(idf_verify_environment)
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 6fd68de14..9143776f5 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -1,14 +1,14 @@
 include(ExternalProject)
 
-add_compile_options("-I${CMAKE_BINARY_DIR}")
+macro(kconfig_set_variables)
+  set(MCONF ${IDF_PATH}/tools/kconfig/mconf)
 
-set(MCONF ${IDF_PATH}/tools/kconfig/mconf)
+  set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
+  set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
+  set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
 
-set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
-set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
-set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
-
-set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
+  set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
+endmacro()
 
 # Use the existing Makefile to build mconf when needed
 #
@@ -24,7 +24,7 @@ ExternalProject_Add(mconf
   )
 
 # Find all Kconfig files for all components
-function(build_component_config)
+function(kconfig_process_config)
   file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
   set(kconfigs )
   set(kconfigs_projbuild )
diff --git a/idf.cmake b/tools/cmake/project.cmake
similarity index 52%
rename from idf.cmake
rename to tools/cmake/project.cmake
index efb4631d2..164e923e6 100644
--- a/idf.cmake
+++ b/tools/cmake/project.cmake
@@ -2,16 +2,7 @@
 #
 cmake_minimum_required(VERSION 3.5)
 
-#
-# Verify the project configured the environment correctly
-#
-if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
-  message(FATAL_ERROR "The parent project CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
-    "before including this file. "
-    "Update CMakeLists.txt to match the template project and delete CMakeCache.txt before "
-    "re-running cmake.")
-endif()
-
+# Set IDF_PATH, as nothing else will work without this
 set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
   # Documentation says you should set IDF_PATH in your environment, but we
@@ -20,11 +11,6 @@ if(NOT IDF_PATH)
   set($ENV{IDF_PATH} "${IDF_PATH}")
 endif()
 
-# PROJECT_PATH has the path to the IDF project (top-level cmake directory)
-#
-# (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
-set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
-
 #
 # Load cmake modules
 #
@@ -33,43 +19,34 @@ include(GetGitRevisionDescription)
 include(utilities)
 include(components)
 include(kconfig)
-include(crosstool_version_check)
 include(git_submodules)
 include(idf_functions)
 
-#
-# Warn if the toolchain version doesn't match
-#
-gcc_version_check("5.2.0")
-crosstool_version_check("1.22.0-80-g6c4433a")
+# Verify the environment is configured correctly
+idf_verify_environment()
 
-#
-# Configure optional variables
-#
-set_default(EXTRA_COMPONENT_DIRS "")
+# Set global variables used by rest of the build
+idf_set_global_variables()
 
-# Note: "main" is no longer a component...
-#
-set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
-spaces2list(COMPONENT_DIRS)
-
-spaces2list(COMPONENTS)
 # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
-find_all_components("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
-build_component_config()
+components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
+
+kconfig_set_variables()
+
+kconfig_process_config()
 
 # Include sdkconfig.cmake so rest of the build knows the configuration
 include(${SDKCONFIG_CMAKE})
 
-#
 # Add some idf-wide definitions
 idf_set_global_compiler_options()
 
+# Check git version (may trigger reruns of cmake)
+# & set GIT_REVISION/IDF_VER variable
 git_describe(GIT_REVISION)
 add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
 git_submodule_check("${IDF_PATH}")
 
-add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
 #
 # Add components to the build
@@ -79,10 +56,9 @@ foreach(component ${COMPONENT_PATHS})
   add_subdirectory(${component} ${component_name})
 endforeach()
 
-finish_component_registration()
+components_finish_registration()
 
 # Load the targets for the bootloader subproject
 if(NOT BOOTLOADER_BUILD)
   include(bootloader_subproject)
 endif()
-

From ce6748873dd5df29458e9fe1083310db23cc7126 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 17 Jan 2018 16:25:14 +1100
Subject: [PATCH 010/112] cmake: Add embedding files in components support

Add subscribe_publish AWS example and fixes to allow it to build.
---
 components/esp32/CMakeLists.txt               |  2 +
 components/mbedtls/CMakeLists.txt             |  2 +-
 .../aws_iot/subscribe_publish/CMakeLists.txt  | 18 ++++++
 tools/cmake/components.cmake                  | 37 ++++++++++--
 tools/cmake/idf_functions.cmake               |  6 +-
 tools/cmake/kconfig.cmake                     |  2 +-
 tools/cmake/scripts/data_file_to_c.cmake      | 56 +++++++++++++++++++
 tools/cmake/utilities.cmake                   | 27 +++++++++
 8 files changed, 139 insertions(+), 11 deletions(-)
 create mode 100644 examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
 create mode 100644 tools/cmake/scripts/data_file_to_c.cmake

diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 9a9d4c783..447e95d23 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -10,6 +10,8 @@ if(BOOTLOADER_BUILD)
 else()
   # Regular app build
 
+  set(COMPONENT_SRCDIRS ". hwcrypto")
+
   register_component()
 
   target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
diff --git a/components/mbedtls/CMakeLists.txt b/components/mbedtls/CMakeLists.txt
index 96ac14d12..293ad00ce 100644
--- a/components/mbedtls/CMakeLists.txt
+++ b/components/mbedtls/CMakeLists.txt
@@ -4,5 +4,5 @@ set(COMPONENT_SRCDIRS library port)
 register_component()
 
 target_compile_definitions(mbedtls PUBLIC
-	MBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
+	-DMBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
 )
diff --git a/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
new file mode 100644
index 000000000..bf0e56610
--- /dev/null
+++ b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
@@ -0,0 +1,18 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
+project(idf_project ASM C CXX)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+add_executable(subscribe_publish.elf
+  main/subscribe_publish_sample.c)
+
+target_add_binary_data(subscribe_publish.elf main/certs/aws-root-ca.pem TEXT)
+target_add_binary_data(subscribe_publish.elf main/certs/certificate.pem.crt TEXT)
+target_add_binary_data(subscribe_publish.elf main/certs/private.pem.key TEXT)
+
+# TODO: handle IDF_CI_BUILD dummy cert files here
+
+target_link_libraries(subscribe_publish.elf ${COMPONENT_LIBRARIES})
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 3a9e1fc2f..9930a44eb 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -76,14 +76,26 @@ function(register_component)
     endforeach()
   endif()
 
+  # binaries to embed directly in library
+  spaces2list(COMPONENT_EMBED_FILES)
+  spaces2list(COMPONENT_EMBED_TXTFILES)
+  foreach(embed_data ${COMPONENT_EMBED_FILES} ${COMPONENT_EMBED_TXTFILES})
+    if (embed_data IN_LIST COMPONENT_EMBED_TXTFILES)
+      set(embed_type "TEXT")
+    else()
+      set(embed_type "BINARY")
+    endif()
+    target_add_binary_data("${component}" "${embed_data}" "${embed_type}")
+  endforeach()
+
   # add public includes from other components when building this component
-  if(COMPONENT_SRCS)
-    add_library(${component} STATIC ${COMPONENT_SRCS})
+  if(COMPONENT_SRCS OR embed_binaries)
+    add_library(${component} STATIC ${COMPONENT_SRCS} ${embed_binaries})
     set(include_type PUBLIC)
   else()
     add_library(${component} INTERFACE) # header-only component
     set(include_type INTERFACE)
-  endif(COMPONENT_SRCS)
+  endif(COMPONENT_SRCS OR embed_binaries)
 
   foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
     get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
@@ -117,9 +129,13 @@ function(components_finish_registration)
       if (${a_type} STREQUAL STATIC_LIBRARY)
         foreach(b ${COMPONENTS})
           if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
+            # Add all public compile options from b in a
             target_include_directories(${a} PRIVATE
-              $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>
-              )
+              $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
+            target_compile_definitions(${a} PRIVATE
+              $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
+            target_compile_options(${a} PRIVATE
+              $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
           endif()
         endforeach(b)
       endif(${a_type} STREQUAL STATIC_LIBRARY)
@@ -130,4 +146,15 @@ function(components_finish_registration)
 
   # set COMPONENT_LIBRARIES in top-level scope
   set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES}" PARENT_SCOPE)
+
+  # Embedded binary & text files
+  spaces2list(COMPONENT_EMBED_FILES)
+  foreach(embed_src ${COMPONENT_EMBED_FILES})
+    target_add_binary_data(${component} "${embed_src}" BINARY)
+  endforeach()
+  spaces2list(COMPONENT_EMBED_TXTFILES)
+  foreach(embed_src ${COMPONENT_EMBED_TXTFILES})
+    target_add_binary_data(${component} "${embed_src}" TEXT)
+  endforeach()
+
 endfunction(components_finish_registration)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 34785b102..a9100b7db 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -69,7 +69,7 @@ function(idf_set_global_compiler_options)
   endif()
 
   # Always generate debug symbols (even in Release mode, these don't
-  # go itno ther final binary
+  # go into the final binary so have no impact on size)
   add_compile_options(-ggdb)
 
   add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
@@ -107,6 +107,4 @@ function(idf_verify_environment)
   gcc_version_check("5.2.0")
   crosstool_version_check("1.22.0-80-g6c4433a")
 
-  
-
-endfunction(idf_verify_environment)
+endfunction()
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 9143776f5..d7ec6f4c3 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -31,7 +31,7 @@ function(kconfig_process_config)
 
   # Find Kconfig and Kconfig.projbuild for each component as applicable
   # if any of these change, cmake should rerun
-  foreach(dir ${COMPONENT_PATHS})
+  foreach(dir ${COMPONENT_PATHS} "${CMAKE_SOURCE_DIR}/main")
     file(GLOB kconfig "${dir}/Kconfig")
     if(kconfig)
       set(kconfigs "${kconfigs} ${kconfig}")
diff --git a/tools/cmake/scripts/data_file_to_c.cmake b/tools/cmake/scripts/data_file_to_c.cmake
new file mode 100644
index 000000000..6d20eca7e
--- /dev/null
+++ b/tools/cmake/scripts/data_file_to_c.cmake
@@ -0,0 +1,56 @@
+#
+# Convert a file (text or binary) into a C source file suitable
+# for gcc. Designed to replicate 'objcopy' with more predictable
+# naming, and supports appending a null byte for embedding text as
+# a string.
+#
+# Designed to be run as a script with "cmake -P"
+#
+# Set variables DATA_FILE, SOURCE_FILE, FILE_TYPE when running this.
+#
+# If FILE_TYPE is set to STRING, a null byte is appended to DATA_FILE's contents
+# before it is embedded.
+#
+# If FILE_TYPE is unset (or any other value), DATA_FILE is embedded
+# verbatim.
+#
+#
+if(NOT DATA_FILE)
+  message(FATAL_ERROR "DATA_FILE for converting must be specified")
+endif()
+
+if(NOT SOURCE_FILE)
+  message(FATAL_ERROR "SOURCE_FILE destination must be specified")
+endif()
+
+file(READ "${DATA_FILE}" data HEX)
+
+if(FILE_TYPE STREQUAL "TEXT")
+  set(data "${data}00")  # null-byte terimnation
+endif()
+
+## Convert string of raw hex bytes to lines of hex bytes in C array format
+string(REGEX REPLACE "................................" "\\0\n    " data "${data}")  # 16 bytes per line
+string(REGEX REPLACE "[0-9a-f][0-9a-f]" "0x\\0, " data "${data}")                    # hex formatted C bytes
+string(REGEX REPLACE ", $" "" data "${data}")                                        # trim the last comma (cosmetic)
+
+## Come up with C-friendly name for file
+get_filename_component(source_filename "${DATA_FILE}" NAME)
+string(MAKE_C_IDENTIFIER "${source_filename}" varname)
+
+file(WRITE "${SOURCE_FILE}"  "/*\n")
+file(APPEND "${SOURCE_FILE}" " * Data converted from ${DATA_FILE}\n")
+if(FILE_TYPE STREQUAL "TEXT")
+  file(APPEND "${SOURCE_FILE}" " * (null byte appended)\n")
+endif()
+file(APPEND "${SOURCE_FILE}" " */\n")
+file(APPEND "${SOURCE_FILE}" "#include <stdlib.h>\n")
+file(APPEND "${SOURCE_FILE}" "#include <stddef.h>\n\n")
+
+file(APPEND "${SOURCE_FILE}" "const char ${varname}[] = {\n    ${data}\n    };\n")
+file(APPEND "${SOURCE_FILE}" "const size_t ${varname}_length = sizeof(${varname});\n\n")
+
+# Backwards compatibility, matches objcopy binary symbol names
+file(APPEND "${SOURCE_FILE}" "/* Backwards compatible names, match objcopy -I binary naming */\n")
+file(APPEND "${SOURCE_FILE}" "const char *_binary_${varname}_start = ${varname};\n")
+file(APPEND "${SOURCE_FILE}" "const char *_binary_${varname}_end = ${varname} + sizeof(${varname});\n")
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index ce71f5ced..f7ffcabb0 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -73,6 +73,7 @@ function(move_if_different source destination)
 
 endfunction()
 
+
 # add_compile_options variant for C++ code only
 #
 # This adds global options, set target properties for
@@ -94,3 +95,29 @@ function(add_c_compile_options)
     add_compile_options($<$<COMPILE_LANGUAGE:C>:${option}>)
   endforeach()
 endfunction()
+
+
+# target_add_binary_data adds binary data into the built target,
+# by converting it to a generated source file which is then compiled
+# to a binary object as part of the build
+function(target_add_binary_data target embed_file embed_type)
+
+  get_filename_component(embed_file "${embed_file}" ABSOLUTE BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+
+  get_filename_component(name "${embed_file}" NAME)
+  set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.c")
+
+  add_custom_command(OUTPUT "${embed_srcfile}"
+    COMMAND "${CMAKE_COMMAND}"
+    -D "DATA_FILE=${embed_file}"
+    -D "SOURCE_FILE=${embed_srcfile}"
+    -D "FILE_TYPE=${embed_type}"
+    -P "${IDF_PATH}/tools/cmake/scripts/data_file_to_c.cmake"
+    MAIN_DEPENDENCY "${embed_file}"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}")
+
+  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${embed_srcfile}")
+
+  target_sources("${target}" PRIVATE "${embed_srcfile}")
+endfunction()
+

From 97e01a4c4d1939f0046257ccc2fc8fa67689496d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 17 Jan 2018 16:35:15 +1100
Subject: [PATCH 011/112] cmake: Remove stray tab

---
 components/bt/CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index 7410e19d0..ec18c3375 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -10,7 +10,7 @@ if(CONFIG_BT_ENABLED)
 
     set(COMPONENT_ADD_INCLUDEDIRS ${COMPONENT_ADD_INCLUDEDIRS}
       bluedroid/bta/include
-	  bluedroid/bta/sys/include
+      bluedroid/bta/sys/include
       bluedroid/btcore/include
       bluedroid/device/include
       bluedroid/gki/include

From 3ae48221159844264431208a74b010d2cad0ebb7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 18 Jan 2018 12:12:13 +1100
Subject: [PATCH 012/112] cmake: Add partition table generation

---
 components/partition_table/CMakeLists.txt | 45 +++++++++++++++++++++++
 tools/cmake/project.cmake                 |  2 +
 2 files changed, 47 insertions(+)

diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index bdd55ceea..b8a17b13a 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -1 +1,46 @@
+set(partition_table_offset 0x8000)
+
+# Set partition_csv to the configured partition source file
+#
+if(CONFIG_PARTITION_TABLE_CUSTOM)
+  # Custom filename expands any path relative to the project
+  get_filename_component(partition_csv "${CONFIG_PARTITION_TABLE_CUSTOM}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+else()
+  # Other .csv files are always in the component directory
+  set(partition_csv "${CMAKE_CURRENT_SOURCE_DIR}/${CONFIG_PARTITION_TABLE_FILENAME}")
+endif()
+
+if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
+  set(unsigned_partition_bin "partition-unsigned.bin")
+  set(final_partition_bin "partition.bin")
+  set(final_partition_target "sign_partition_table")
+else()
+  set(unsigned_partition_bin "partition.bin")
+  set(final_partition_bin "partition.bin")
+  set(final_partition_target "build_partition_table")
+endif()
+
+add_custom_target(build_partition_table ALL
+  "${PYTHON}" "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py" -q
+  ${partition_csv} ${unsigned_partition_bin}
+  BYPRODUCTS ${unsigned_partition_bin}
+  DEPENDS ${partition_csv} "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py"
+  VERBATIM)
+
+# Add signing steps
+if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
+  get_filename_component(secure_boot_signing_key "${CONFIG_SECURE_BOOT_SIGNING_KEY}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+
+  add_custom_target(signpartition_table ALL
+    "${PYTHON}" "${ESPSECUREPY}" sign_data --keyfile "${secure_boot_signing_key}" -o "${final_partition_bin}" "${unsigned_partition_bin}"
+    BYPRODUCTS "${final_partition_bin}"
+    DEPENDS "${unsigned_partition_bin}"
+    VERBATIM)
+
+endif()
+
+# Use global properties ESPTOOL_WRITE_FLASH_ARGS & FLASH_DEPENDS to pass this info to the esptool component for flashing
+set_property(GLOBAL APPEND_STRING PROPERTY ESPTOOL_WRITE_FLASH_ARGS "${final_partition_bin} ${partition_table_offset} ")
+set_property(GLOBAL APPEND PROPERTY FLASH_DEPENDS "${final_partition_target}")
+
 register_config_only_component()
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 164e923e6..f45d7166d 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -38,6 +38,8 @@ kconfig_process_config()
 # Include sdkconfig.cmake so rest of the build knows the configuration
 include(${SDKCONFIG_CMAKE})
 
+set(PYTHON "${CONFIG_PYTHON}")
+
 # Add some idf-wide definitions
 idf_set_global_compiler_options()
 

From 674d398c9376e1de3e1437c67ea4bc8a7ac25044 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 19 Jan 2018 15:47:49 +1100
Subject: [PATCH 013/112] cmake: Add partition table, and .bin file targets

---
 .../bootloader/subproject/CMakeLists.txt      | 19 +++----
 components/esptool_py/project_include.cmake   | 48 ++++++++++++++++++
 components/partition_table/CMakeLists.txt     | 31 +++++++-----
 .../get-started/hello_world/CMakeLists.txt    | 12 ++---
 tools/cmake/components.cmake                  | 35 +++++++------
 tools/cmake/idf_functions.cmake               | 50 +++++++++++++------
 tools/cmake/project.cmake                     | 18 ++++++-
 tools/cmake/utilities.cmake                   |  7 ++-
 8 files changed, 156 insertions(+), 64 deletions(-)
 create mode 100644 components/esptool_py/project_include.cmake

diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index ab7b5aaa6..1931392d5 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -1,24 +1,21 @@
 cmake_minimum_required(VERSION 3.5)
 set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
-project(idf_bootloader ASM C CXX)
+
+if(NOT SDKCONFIG)
+  message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the parent build process.")
+endif()
+
+project(bootloader ASM C CXX)
 
 set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash micro-ecc soc)
-
 set(BOOTLOADER_BUILD 1)
 set(IS_BOOTLOADER_BUILD 1)  # deprecated, use BOOTLOADER_BUILD
 add_definitions(-DBOOTLOADER_BUILD=1)
 
-if(NOT SDKCONFIG)
-  message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the app build process.")
-endif()
-
-include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-
-add_executable(bootloader.elf
-  main/bootloader_start.c
+set(MAIN_SRCS main/bootloader_start.c
   main/flash_qio_mode.c)
 
-target_link_libraries(bootloader.elf ${COMPONENT_LIBRARIES})
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
 target_link_libraries(bootloader.elf "-L ${CMAKE_CURRENT_SOURCE_DIR}/main")
 target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
diff --git a/components/esptool_py/project_include.cmake b/components/esptool_py/project_include.cmake
new file mode 100644
index 000000000..52fc289ee
--- /dev/null
+++ b/components/esptool_py/project_include.cmake
@@ -0,0 +1,48 @@
+# Set some global esptool.py variables
+set(ESPTOOLPY "${PYTHON}" "${CMAKE_CURRENT_LIST_DIR}/esptool/esptool.py" --chip esp32)
+set(ESPSECUREPY "${PYTHON}" "${CMAKE_CURRENT_LIST_DIR}/esptool/espsecure.py")
+
+set(ESPPORT $ENV{ESPPORT})
+if(NOT ESPPORT)
+  set(ESPPORT ${CONFIG_ESPTOOLPY_PORT})
+endif()
+
+set(ESPBAUD $ENV{ESPPORT})
+if(NOT ESPBAUD)
+  set(ESPPORT ${CONFIG_ESPTOOLPY_PORT})
+endif()
+
+set(ESPFLASHMODE ${CONFIG_ESPTOOLPY_FLASHMODE})
+set(ESPFLASHFREQ ${CONFIG_ESPTOOLPY_FLASHFREQ})
+set(ESPFLASHSIZE ${CONFIG_ESPTOOLPY_FLASHSIZE})
+
+set(ESPTOOLPY_SERIAL "${ESPTOOLPY}" --port "${ESPPORT}" --baud ${ESPBAUD})
+
+if(CONFIG_ESPTOOLPY_FLASHSIZE_DETECT)
+  set(flashsize_arg detect)
+else()
+  set(flashsize_arg ${ESPFLASHSIZE})
+endif()
+
+set(ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS --flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${ESPFLASHSIZE})
+
+set(ESPTOOLPY_WRITE_FLASH_OPTIONS --flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${flashsize_Arg})
+
+set(ESPTOOLPY_WRITE_FLASH ${ESPTOOLPY_SERIAL} write_flash ${ESPTOOLPY_WRITE_FLASH_OPTIONS})
+
+#
+# Add 'binary' target - generates with elf2image
+#
+add_custom_command(OUTPUT "${PROJECT_NAME}.bin"
+  COMMAND ${ESPTOOLPY} elf2image ${ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS} -o "${PROJECT_NAME}.bin" "${PROJECT_NAME}.elf"
+  DEPENDS ${PROJECT_NAME}.elf
+  VERBATIM
+  )
+add_custom_target(binary ALL DEPENDS "${PROJECT_NAME}.bin")
+
+#
+# Add 'flash' target - not all build systems can run this directly
+#
+add_custom_target(flash DEPENDS binary partition_table bootloader_subproject)
+# TODO: this target should call "idftool" not esptool directly, so it can
+# override things (port, baud, etc) at runtime not configure time
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index b8a17b13a..f39408806 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -20,27 +20,34 @@ else()
   set(final_partition_target "build_partition_table")
 endif()
 
-add_custom_target(build_partition_table ALL
-  "${PYTHON}" "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py" -q
-  ${partition_csv} ${unsigned_partition_bin}
-  BYPRODUCTS ${unsigned_partition_bin}
-  DEPENDS ${partition_csv} "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py"
-  VERBATIM)
+if(CONFIG_PARTITION_TABLE_MD5)
+    set(md5_opt --disable-md5sum)
+endif()
+
+if(CONFIG_ESPTOOLPY_FLASHSIZE)
+    set(flashsize_opt --flash-size ${CONFIG_ESPTOOLPY_FLASHSIZE})
+endif()
+
+add_custom_command(OUTPUT "${unsigned_partition_bin}"
+    COMMAND "${PYTHON}" "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py" -q ${md5_opt} ${flashsize_opt}
+    ${partition_csv} ${unsigned_partition_bin}
+    DEPENDS ${partition_csv} "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py"
+    VERBATIM)
 
 # Add signing steps
 if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
   get_filename_component(secure_boot_signing_key "${CONFIG_SECURE_BOOT_SIGNING_KEY}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
 
-  add_custom_target(signpartition_table ALL
-    "${PYTHON}" "${ESPSECUREPY}" sign_data --keyfile "${secure_boot_signing_key}" -o "${final_partition_bin}" "${unsigned_partition_bin}"
-    BYPRODUCTS "${final_partition_bin}"
+  add_custom_command(OUTPUT "${final_partition_bin}"
+    COMMAND "${PYTHON}" "${ESPSECUREPY}" sign_data --keyfile "${secure_boot_signing_key}" -o "${final_partition_bin}" "${unsigned_partition_bin}"
     DEPENDS "${unsigned_partition_bin}"
     VERBATIM)
 
 endif()
 
-# Use global properties ESPTOOL_WRITE_FLASH_ARGS & FLASH_DEPENDS to pass this info to the esptool component for flashing
-set_property(GLOBAL APPEND_STRING PROPERTY ESPTOOL_WRITE_FLASH_ARGS "${final_partition_bin} ${partition_table_offset} ")
-set_property(GLOBAL APPEND PROPERTY FLASH_DEPENDS "${final_partition_target}")
+add_custom_target(partition_table ALL DEPENDS "${final_partition_bin}")
+
+# Use global properties ESPTOOL_WRITE_FLASH_ARGS to pass this info to build hte list of esptool write arguments for flashing
+set_property(GLOBAL APPEND_STRING PROPERTY ESPTOOL_WRITE_FLASH_ARGS "${partition_table_offset} ${final_partition_bin} ")
 
 register_config_only_component()
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
index 4e66c5efd..4ae205fa2 100644
--- a/examples/get-started/hello_world/CMakeLists.txt
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -1,12 +1,10 @@
-# The following four lines of boilerplate have to be in your project's CMakeLists
+# The following five lines of boilerplate have to be in your project's CMakeLists
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
-project(idf_project ASM C CXX)
+
+project(hello-world ASM C CXX)
+
+set(MAIN_SRCS main/hello_world_main.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-
-add_executable(hello_world.elf
-  main/hello_world_main.c)
-
-target_link_libraries(hello_world.elf ${COMPONENT_LIBRARIES})
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 9930a44eb..8e2b85775 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -76,6 +76,15 @@ function(register_component)
     endforeach()
   endif()
 
+  # add public includes from other components when building this component
+  if(COMPONENT_SRCS OR embed_binaries)
+    add_library(${component} STATIC ${COMPONENT_SRCS})
+    set(include_type PUBLIC)
+  else()
+    add_library(${component} INTERFACE) # header-only component
+    set(include_type INTERFACE)
+  endif()
+
   # binaries to embed directly in library
   spaces2list(COMPONENT_EMBED_FILES)
   spaces2list(COMPONENT_EMBED_TXTFILES)
@@ -88,20 +97,13 @@ function(register_component)
     target_add_binary_data("${component}" "${embed_data}" "${embed_type}")
   endforeach()
 
-  # add public includes from other components when building this component
-  if(COMPONENT_SRCS OR embed_binaries)
-    add_library(${component} STATIC ${COMPONENT_SRCS} ${embed_binaries})
-    set(include_type PUBLIC)
-  else()
-    add_library(${component} INTERFACE) # header-only component
-    set(include_type INTERFACE)
-  endif(COMPONENT_SRCS OR embed_binaries)
-
+  # add public includes
   foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
     get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
     target_include_directories(${component} ${include_type} ${include_dir})
   endforeach()
 
+  # add private includes
   foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
     if (${include_type} STREQUAL INTERFACE)
       message(FATAL_ERROR "Component ${component} can't have no source files and COMPONENT_PRIV_INCLUDEDIRS set.")
@@ -123,10 +125,10 @@ function(components_finish_registration)
   # each component should see the include directories of each other
   #
   # (we can't do this until all components are registered, because if(TARGET ...) won't work
-  foreach(a ${COMPONENTS})
+  foreach(a ${COMPONENTS} ${CMAKE_PROJECT_NAME}.elf)
     if (TARGET ${a})
       get_target_property(a_type ${a} TYPE)
-      if (${a_type} STREQUAL STATIC_LIBRARY)
+      if (${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
         foreach(b ${COMPONENTS})
           if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
             # Add all public compile options from b in a
@@ -138,15 +140,14 @@ function(components_finish_registration)
               $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
           endif()
         endforeach(b)
-      endif(${a_type} STREQUAL STATIC_LIBRARY)
+      endif(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
 
-      set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
+      if (${a_type} MATCHES .+_LIBRARY)
+        set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
+      endif()
     endif()
   endforeach()
 
-  # set COMPONENT_LIBRARIES in top-level scope
-  set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES}" PARENT_SCOPE)
-
   # Embedded binary & text files
   spaces2list(COMPONENT_EMBED_FILES)
   foreach(embed_src ${COMPONENT_EMBED_FILES})
@@ -157,4 +158,6 @@ function(components_finish_registration)
     target_add_binary_data(${component} "${embed_src}" TEXT)
   endforeach()
 
+  target_link_libraries(${CMAKE_PROJECT_NAME}.elf ${COMPONENT_LIBRARIES})
+
 endfunction(components_finish_registration)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index a9100b7db..d7f9bb235 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -3,6 +3,7 @@
 include(crosstool_version_check)
 
 macro(idf_set_global_variables)
+  # Note that CONFIG_xxx is not available when this function is called
 
   set_default(EXTRA_COMPONENT_DIRS "")
 
@@ -18,6 +19,9 @@ macro(idf_set_global_variables)
 
   spaces2list(COMPONENTS)
 
+  # Tell cmake to drop executables in the top-level build dir
+  set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}")
+
 endmacro()
 
 # Add all the IDF global compiler & preprocessor options
@@ -76,27 +80,18 @@ function(idf_set_global_compiler_options)
 
 endfunction(idf_set_global_compiler_options)
 
-# Override add_executable to add IDF-specific
-# linker flags & map file to all built executables
-function(add_executable target)
-  get_filename_component(basename ${target} NAME_WE)
-  set(mapfile "${basename}.map")
-
-  _add_executable(${ARGV})
-
-  target_link_libraries(${target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
-
-  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
-endfunction(add_executable)
-
 
 # Verify the IDF environment is configured correctly (environment, toolchain, etc)
 function(idf_verify_environment)
 
+  if(NOT CMAKE_PROJECT_NAME)
+    message(FATAL_ERROR "Project top-level CMakeLists.txt file must call project() before including project.cmake")
+  endif()
+
   # Check toolchain is configured properly in cmake
   if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
-    message(FATAL_ERROR "The parent project CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
-      "before including this file. "
+    message(FATAL_ERROR "Project top-level CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
+      "before including project.cmake.\n"
       "Update CMakeLists.txt to match the template project and delete CMakeCache.txt before "
       "re-running cmake.")
   endif()
@@ -108,3 +103,28 @@ function(idf_verify_environment)
   crosstool_version_check("1.22.0-80-g6c4433a")
 
 endfunction()
+
+# idf_add_executable
+#
+# Calls add_executable to add the final project executable
+# Adds .map & .bin file targets
+# Sets up flash-related targets
+function(idf_add_executable)
+  set(exe_target ${PROJECT_NAME}.elf)
+
+  spaces2list(${MAIN_SRCS})
+  add_executable(${exe_target} "${MAIN_SRCS}")
+
+  add_map_file(${exe_target})
+endfunction(idf_add_executable)
+
+
+# add_map_file
+#
+# Set linker args for 'exe_target' to generate a linker Map file
+function(add_map_file exe_target)
+  get_filename_component(basename ${exe_target} NAME_WE)
+  set(mapfile "${basename}.map")
+  target_link_libraries(${exe_target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
+  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
+endfunction(add_map_file)
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index f45d7166d..a37d6fd0c 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -50,17 +50,31 @@ add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
 git_submodule_check("${IDF_PATH}")
 
 
+# Include any top-level project_include.cmake files from components
+foreach(component ${COMPONENT_PATHS})
+  include_if_exists("${component}/project_include.cmake")
+endforeach()
+
 #
-# Add components to the build
+# Add each component to the build as a library
 #
 foreach(component ${COMPONENT_PATHS})
   get_filename_component(component_name ${component} NAME)
   add_subdirectory(${component} ${component_name})
 endforeach()
 
+#
+# Add the app executable to the build (has name of PROJECT.elf)
+#
+idf_add_executable()
+
+#
+# Finish component registration (add cross-dependencies, make
+# executable dependent on all components.)
+#
 components_finish_registration()
 
-# Load the targets for the bootloader subproject
+# Define the external target to build the bootloader subproject
 if(NOT BOOTLOADER_BUILD)
   include(bootloader_subproject)
 endif()
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index f7ffcabb0..045b88497 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -102,7 +102,7 @@ endfunction()
 # to a binary object as part of the build
 function(target_add_binary_data target embed_file embed_type)
 
-  get_filename_component(embed_file "${embed_file}" ABSOLUTE BASE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+  get_filename_component(embed_file "${embed_file}" ABSOLUTE)
 
   get_filename_component(name "${embed_file}" NAME)
   set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.c")
@@ -121,3 +121,8 @@ function(target_add_binary_data target embed_file embed_type)
   target_sources("${target}" PRIVATE "${embed_srcfile}")
 endfunction()
 
+macro(include_if_exists path)
+  if(EXISTS "${path}")
+    include("${path}")
+  endif()
+endmacro(include_if_exists)

From 3fac2b2ddc333d810d2281b786debe2927784a17 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 19 Jan 2018 16:00:41 +1100
Subject: [PATCH 014/112] cmake: Refactor bootloader_subproject into the
 bootloader component itself

---
 .../bootloader/project_include.cmake             | 16 ++++++++++------
 components/bootloader/subproject/CMakeLists.txt  |  3 +--
 tools/cmake/project.cmake                        |  7 +------
 3 files changed, 12 insertions(+), 14 deletions(-)
 rename tools/cmake/bootloader_subproject.cmake => components/bootloader/project_include.cmake (71%)

diff --git a/tools/cmake/bootloader_subproject.cmake b/components/bootloader/project_include.cmake
similarity index 71%
rename from tools/cmake/bootloader_subproject.cmake
rename to components/bootloader/project_include.cmake
index c141fadd3..bfefcb8a2 100644
--- a/tools/cmake/bootloader_subproject.cmake
+++ b/components/bootloader/project_include.cmake
@@ -1,18 +1,22 @@
+if(IS_BOOTLOADER_BUILD)
+  return()  # don't keep recursing!
+endif()
+
 # Glue to build the bootloader subproject binary as an external
 # cmake project under this one
 #
 #
-set(bootloader_subproject_build_dir "${CMAKE_BINARY_DIR}/bootloader_subproject")
+set(bootloader_build_dir "${CMAKE_BINARY_DIR}/bootloader")
 set(bootloader_binary_files
-  "${bootloader_subproject_build_dir}/bootloader.elf"
-  "${bootloader_subproject_build_dir}/bootloader.bin"
-  "${bootloader_subproject_build_dir}/bootloader.map"
+  "${bootloader_build_dir}/bootloader.elf"
+  "${bootloader_build_dir}/bootloader.bin"
+  "${bootloader_build_dir}/bootloader.map"
   )
 
-ExternalProject_Add(bootloader_subproject
+ExternalProject_Add(bootloader
   # TODO: support overriding the bootloader in COMPONENT_PATHS
   SOURCE_DIR "${IDF_PATH}/components/bootloader/subproject"
-  BINARY_DIR "${bootloader_subproject_build_dir}"
+  BINARY_DIR "${bootloader_build_dir}"
   CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH="${IDF_PATH}"
   INSTALL_COMMAND ""
   BUILD_ALWAYS 1  # no easy way around this...
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index 1931392d5..f3cc23ac1 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -12,8 +12,7 @@ set(BOOTLOADER_BUILD 1)
 set(IS_BOOTLOADER_BUILD 1)  # deprecated, use BOOTLOADER_BUILD
 add_definitions(-DBOOTLOADER_BUILD=1)
 
-set(MAIN_SRCS main/bootloader_start.c
-  main/flash_qio_mode.c)
+set(MAIN_SRCS main/bootloader_start.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index a37d6fd0c..e8e3cc7ca 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -70,11 +70,6 @@ idf_add_executable()
 
 #
 # Finish component registration (add cross-dependencies, make
-# executable dependent on all components.)
+# executable dependent on all components)
 #
 components_finish_registration()
-
-# Define the external target to build the bootloader subproject
-if(NOT BOOTLOADER_BUILD)
-  include(bootloader_subproject)
-endif()

From 4f1a856dbfd752336cd71730105e02ad8c045541 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 19 Jan 2018 16:22:08 +1100
Subject: [PATCH 015/112] cmake: Remove defaults for COMPONENT_SRCDIRS,
 COMPONENT_SRCS, COMPONENT_ADD_INCLUDEDIRS

* Philosophical: "explicit is better than implicit".
* Practical: Allows useful errors if invalid directories given in components as the defaults aren't
  always used. Also trims the -I path from a number of components that have no actual include
  directory.
* Simplifies knowing which components will be header-only and which won't
---
 components/app_trace/CMakeLists.txt           |  3 ++
 components/app_update/CMakeLists.txt          |  3 ++
 components/bootloader_support/CMakeLists.txt  |  1 +
 components/console/CMakeLists.txt             |  2 ++
 components/cxx/CMakeLists.txt                 |  1 +
 components/driver/CMakeLists.txt              |  4 ++-
 components/esp32/CMakeLists.txt               |  1 +
 components/esp_adc_cal/CMakeLists.txt         |  3 ++
 components/ethernet/CMakeLists.txt            |  1 +
 components/expat/CMakeLists.txt               |  1 -
 components/fatfs/CMakeLists.txt               |  2 +-
 components/freertos/CMakeLists.txt            |  1 +
 components/heap/CMakeLists.txt                |  2 ++
 components/idf_test/CMakeLists.txt            |  2 +-
 components/jsmn/CMakeLists.txt                |  4 ++-
 components/json/CMakeLists.txt                |  4 +--
 components/log/CMakeLists.txt                 |  2 ++
 components/mdns/CMakeLists.txt                |  3 ++
 components/newlib/CMakeLists.txt              |  1 +
 components/nvs_flash/CMakeLists.txt           |  2 +-
 components/sdmmc/CMakeLists.txt               |  3 ++
 components/tcpip_adapter/CMakeLists.txt       |  3 ++
 components/ulp/CMakeLists.txt                 |  3 ++
 components/vfs/CMakeLists.txt                 |  3 ++
 components/wear_levelling/CMakeLists.txt      |  2 ++
 components/wpa_supplicant/CMakeLists.txt      |  2 +-
 components/xtensa-debug-module/CMakeLists.txt |  3 ++
 .../aws_iot/subscribe_publish/CMakeLists.txt  | 13 +++----
 tools/cmake/components.cmake                  | 36 +++++++++++--------
 tools/cmake/utilities.cmake                   |  1 +
 30 files changed, 80 insertions(+), 32 deletions(-)

diff --git a/components/app_trace/CMakeLists.txt b/components/app_trace/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/app_trace/CMakeLists.txt
+++ b/components/app_trace/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/app_update/CMakeLists.txt
+++ b/components/app_update/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/bootloader_support/CMakeLists.txt b/components/bootloader_support/CMakeLists.txt
index f27310dfc..1e5c52fb8 100644
--- a/components/bootloader_support/CMakeLists.txt
+++ b/components/bootloader_support/CMakeLists.txt
@@ -3,6 +3,7 @@ set(COMPONENT_SRCDIRS "src")
 if(${BOOTLOADER_BUILD})
   set(COMPONENT_ADD_INCLUDEDIRS "include include_priv")
 else()
+  set(COMPONENT_ADD_INCLUDEDIRS "include")
   set(COMPONENT_PRIV_INCLUDEDIRS "include_priv")
 endif()
 
diff --git a/components/console/CMakeLists.txt b/components/console/CMakeLists.txt
index d1187256b..1c5648654 100644
--- a/components/console/CMakeLists.txt
+++ b/components/console/CMakeLists.txt
@@ -1,3 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS .)
 set(COMPONENT_SRCDIRS linenoise argtable3 .)
+
 register_component()
 
diff --git a/components/cxx/CMakeLists.txt b/components/cxx/CMakeLists.txt
index bf51565c4..c7341ceab 100644
--- a/components/cxx/CMakeLists.txt
+++ b/components/cxx/CMakeLists.txt
@@ -1,3 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
 register_component()
 
 target_link_libraries(cxx stdc++)
diff --git a/components/driver/CMakeLists.txt b/components/driver/CMakeLists.txt
index ca0849824..8ccaad2c3 100644
--- a/components/driver/CMakeLists.txt
+++ b/components/driver/CMakeLists.txt
@@ -1,3 +1,5 @@
-set(COMPONENT_PRIV_INCLUDEDIRS include/driver)
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS "include/driver")
 
 register_component()
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 447e95d23..cf0dff1f0 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -11,6 +11,7 @@ else()
   # Regular app build
 
   set(COMPONENT_SRCDIRS ". hwcrypto")
+  set(COMPONENT_ADD_INCLUDEDIRS "include")
 
   register_component()
 
diff --git a/components/esp_adc_cal/CMakeLists.txt b/components/esp_adc_cal/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/esp_adc_cal/CMakeLists.txt
+++ b/components/esp_adc_cal/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/ethernet/CMakeLists.txt b/components/ethernet/CMakeLists.txt
index 4e20fbead..a9eb90370 100644
--- a/components/ethernet/CMakeLists.txt
+++ b/components/ethernet/CMakeLists.txt
@@ -1,3 +1,4 @@
 set(COMPONENT_SRCDIRS . eth_phy)
+set(COMPONENT_ADD_INCLUDEDIRS "include")
 
 register_component()
diff --git a/components/expat/CMakeLists.txt b/components/expat/CMakeLists.txt
index 02445015c..c35d79ce6 100644
--- a/components/expat/CMakeLists.txt
+++ b/components/expat/CMakeLists.txt
@@ -1,5 +1,4 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include include/expat)
-
 set(COMPONENT_SRCDIRS library port)
 
 register_component()
diff --git a/components/fatfs/CMakeLists.txt b/components/fatfs/CMakeLists.txt
index 2f3a88826..c9f5a0fcf 100644
--- a/components/fatfs/CMakeLists.txt
+++ b/components/fatfs/CMakeLists.txt
@@ -1,4 +1,4 @@
+set(COMPONENT_SRCDIRS src)
 set(COMPONENT_ADD_INCLUDEDIRS src)
-set(COMPONENT_SRCDIRS src/option src)
 
 register_component()
diff --git a/components/freertos/CMakeLists.txt b/components/freertos/CMakeLists.txt
index 1c6a9523b..0a5172dc1 100644
--- a/components/freertos/CMakeLists.txt
+++ b/components/freertos/CMakeLists.txt
@@ -1,5 +1,6 @@
 set(COMPONENT_ADD_INCLUDEDIRS include)
 set(COMPONENT_PRIV_INCLUDEDIRS include/freertos)
+set(COMPONENT_SRCDIRS ".")
 register_component()
 
 target_link_libraries(freertos "-Wl,--undefined=uxTopUsedPriority")
diff --git a/components/heap/CMakeLists.txt b/components/heap/CMakeLists.txt
index 015daa9b7..6fd009ae9 100644
--- a/components/heap/CMakeLists.txt
+++ b/components/heap/CMakeLists.txt
@@ -4,6 +4,8 @@ if(NOT CONFIG_HEAP_POISONING_DISABLED)
   set(COMPONENT_SRCS ${COMPONENT_SRCS} multi_heap_poisoning.c)
 endif()
 
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
 
 if(CONFIG_HEAP_TRACING)
diff --git a/components/idf_test/CMakeLists.txt b/components/idf_test/CMakeLists.txt
index 131acae4d..e307838a8 100644
--- a/components/idf_test/CMakeLists.txt
+++ b/components/idf_test/CMakeLists.txt
@@ -1,2 +1,2 @@
-# idf_test will be registered as an INTERFACE library (ie header paths only)
+set(COMPONENT_ADD_INCLUDEDIRS "include")
 register_component()
diff --git a/components/jsmn/CMakeLists.txt b/components/jsmn/CMakeLists.txt
index 817f6e4be..2eabcf5fe 100644
--- a/components/jsmn/CMakeLists.txt
+++ b/components/jsmn/CMakeLists.txt
@@ -1,2 +1,4 @@
-set(COMPONENT_SRCDIRS src)
+set(COMPONENT_SRCDIRS "src")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/json/CMakeLists.txt b/components/json/CMakeLists.txt
index e3559b269..c19ec43fa 100644
--- a/components/json/CMakeLists.txt
+++ b/components/json/CMakeLists.txt
@@ -1,4 +1,4 @@
-set(COMPONENT_SRCDIRS library port)
-set(COMPONENT_ADD_INCLUDEDIRS include port/include)
+set(COMPONENT_SRCDIRS cJSON)
+set(COMPONENT_ADD_INCLUDEDIRS cJSON)
 
 register_component()
diff --git a/components/log/CMakeLists.txt b/components/log/CMakeLists.txt
index 339733b43..eebd20a04 100644
--- a/components/log/CMakeLists.txt
+++ b/components/log/CMakeLists.txt
@@ -1 +1,3 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
 register_component()
diff --git a/components/mdns/CMakeLists.txt b/components/mdns/CMakeLists.txt
index 0ba2e49dc..149dcb0bc 100644
--- a/components/mdns/CMakeLists.txt
+++ b/components/mdns/CMakeLists.txt
@@ -1,2 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS "private_include")
 register_component()
 
diff --git a/components/newlib/CMakeLists.txt b/components/newlib/CMakeLists.txt
index 0fa454cba..09f26c46a 100644
--- a/components/newlib/CMakeLists.txt
+++ b/components/newlib/CMakeLists.txt
@@ -1,3 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS platform_include include)
 
 if(CONFIG_SPIRAM_CACHE_WORKAROUND)
diff --git a/components/nvs_flash/CMakeLists.txt b/components/nvs_flash/CMakeLists.txt
index 7a9584c6d..5970a7915 100644
--- a/components/nvs_flash/CMakeLists.txt
+++ b/components/nvs_flash/CMakeLists.txt
@@ -1,4 +1,4 @@
-set(COMPONENT_ADD_INCLUDEDIRS include)
 set(COMPONENT_SRCDIRS src)
+set(COMPONENT_ADD_INCLUDEDIRS include)
 
 register_component()
diff --git a/components/sdmmc/CMakeLists.txt b/components/sdmmc/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/sdmmc/CMakeLists.txt
+++ b/components/sdmmc/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/tcpip_adapter/CMakeLists.txt b/components/tcpip_adapter/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/tcpip_adapter/CMakeLists.txt
+++ b/components/tcpip_adapter/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/ulp/CMakeLists.txt b/components/ulp/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/ulp/CMakeLists.txt
+++ b/components/ulp/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/vfs/CMakeLists.txt b/components/vfs/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/vfs/CMakeLists.txt
+++ b/components/vfs/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/components/wear_levelling/CMakeLists.txt b/components/wear_levelling/CMakeLists.txt
index f4f2f14ec..a72d0f565 100644
--- a/components/wear_levelling/CMakeLists.txt
+++ b/components/wear_levelling/CMakeLists.txt
@@ -1,2 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS private_include)
 register_component()
diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
index 73c7294a6..0b06eeeb4 100644
--- a/components/wpa_supplicant/CMakeLists.txt
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -1,5 +1,5 @@
-set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto)
+set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 
 register_component()
 
diff --git a/components/xtensa-debug-module/CMakeLists.txt b/components/xtensa-debug-module/CMakeLists.txt
index 339733b43..ba2fa9c7e 100644
--- a/components/xtensa-debug-module/CMakeLists.txt
+++ b/components/xtensa-debug-module/CMakeLists.txt
@@ -1 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
 register_component()
diff --git a/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
index bf0e56610..297e7b73a 100644
--- a/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
+++ b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
@@ -2,17 +2,14 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
-project(idf_project ASM C CXX)
+
+project(subscribe_publish ASM C CXX)
+
+set(MAIN_SRCS main/subscribe_publish_sample.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 
-add_executable(subscribe_publish.elf
-  main/subscribe_publish_sample.c)
-
+# Embed the certificate data directly in the built binary
 target_add_binary_data(subscribe_publish.elf main/certs/aws-root-ca.pem TEXT)
 target_add_binary_data(subscribe_publish.elf main/certs/certificate.pem.crt TEXT)
 target_add_binary_data(subscribe_publish.elf main/certs/private.pem.key TEXT)
-
-# TODO: handle IDF_CI_BUILD dummy cert files here
-
-target_link_libraries(subscribe_publish.elf ${COMPONENT_LIBRARIES})
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 8e2b85775..bd9481b48 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -54,24 +54,23 @@ function(register_component)
   get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
   get_filename_component(component ${component_dir} NAME)
 
-  if(NOT COMPONENT_SRCDIRS)
-    set(COMPONENT_SRCDIRS ".")
-  endif()
   spaces2list(COMPONENT_SRCDIRS)
-
-  if(NOT COMPONENT_ADD_INCLUDEDIRS)
-    set(COMPONENT_ADD_INCLUDEDIRS "include")
-  endif()
   spaces2list(COMPONENT_ADD_INCLUDEDIRS)
 
-  # if not explicit, build COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
+  # Add to COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
   if(NOT COMPONENT_SRCS)
     foreach(dir ${COMPONENT_SRCDIRS})
-      get_filename_component(dir ${dir} ABSOLUTE BASE_DIR ${component_dir})
-      file(GLOB matches "${dir}/*.[c|S]" "${dir}/*.cpp")
+      get_filename_component(abs_dir ${dir} ABSOLUTE BASE_DIR ${component_dir})
+      if(NOT IS_DIRECTORY ${abs_dir})
+        message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' does not exist")
+      endif()
+
+      file(GLOB matches "${abs_dir}/*.[c|S]" "${abs_dir}/*.cpp")
       if(matches)
         list(SORT matches)
         set(COMPONENT_SRCS "${COMPONENT_SRCS};${matches}")
+      else()
+        message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' contains no source files")
       endif(matches)
     endforeach()
   endif()
@@ -99,17 +98,24 @@ function(register_component)
 
   # add public includes
   foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
-    get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
-    target_include_directories(${component} ${include_type} ${include_dir})
+    get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+    if(NOT IS_DIRECTORY ${abs_dir})
+      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_ADD_INCLUDEDIRS entry '${include_dir}' does not exist")
+    endif()
+    target_include_directories(${component} ${include_type} ${abs_dir})
   endforeach()
 
   # add private includes
   foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
     if (${include_type} STREQUAL INTERFACE)
-      message(FATAL_ERROR "Component ${component} can't have no source files and COMPONENT_PRIV_INCLUDEDIRS set.")
+      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE} sets no component source files but sets COMPONENT_PRIV_INCLUDEDIRS")
     endif()
-    get_filename_component(include_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
-    target_include_directories(${component} PRIVATE ${include_dir})
+
+    get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+    if(NOT IS_DIRECTORY ${abs_dir})
+      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_PRIV_INCLUDEDIRS entry '${niclude_dir}' does not exist")
+    endif()
+    target_include_directories(${component} PRIVATE ${abs_dir})
   endforeach()
 
 endfunction(register_component)
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 045b88497..5c3bac996 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -39,6 +39,7 @@ endfunction()
 #
 function(lines2list variable_name)
   string(REGEX REPLACE "\r?\n" ";" tmp "${${variable_name}}")
+  string(REGEX REPLACE ";;" ";" tmp "${tmp}")
   set("${variable_name}" "${tmp}" PARENT_SCOPE)
 endfunction()
 

From be962a9444d629696199c52bbc6792e8d5437abb Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 19 Jan 2018 16:34:00 +1100
Subject: [PATCH 016/112] cmake: Re-run cmake if submodule commits change or a
 submodule is deinit-ed

---
 tools/cmake/git_submodules.cmake | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/tools/cmake/git_submodules.cmake b/tools/cmake/git_submodules.cmake
index be71f41f6..73e1f35f9 100644
--- a/tools/cmake/git_submodules.cmake
+++ b/tools/cmake/git_submodules.cmake
@@ -41,6 +41,16 @@ else(NOT GIT_FOUND)
       elseif(NOT "${status}" STREQUAL " ")
         message(WARNING "Git submodule ${submodule_path} is out of date. Run 'git submodule update --init --recursive' to fix.")
       endif()
+
+      # Force a re-run of cmake if the submodule's .git file changes or is changed (ie accidental deinit)
+      get_filename_component(submodule_abs_path ${submodule_path} ABSOLUTE BASE_DIR ${root_path})
+      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_abs_path}/.git)
+      # same if the HEAD file in the submodule's directory changes (ie commit changes). This will at least prit the 'out of date' warning
+      set(submodule_head "${root_path}/.git/modules/${submodule_path}/HEAD")
+      if(EXISTS "${submodule_head}")
+        set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_head})
+      endif()
+
     endforeach()
   endfunction(git_submodule_check)
 

From 1f8e07fd8f083625d6e6a78a9a7d42d3e5dc5891 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 22 Jan 2018 14:32:02 +1100
Subject: [PATCH 017/112] cmake: Add sdkconfig.defaults support

---
 tools/cmake/idf_functions.cmake |  5 +++--
 tools/cmake/kconfig.cmake       | 21 +++++++++++++++------
 tools/kconfig_new/confgen.py    | 16 ++++++++++++++--
 3 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index d7f9bb235..101f8e10f 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -111,11 +111,12 @@ endfunction()
 # Sets up flash-related targets
 function(idf_add_executable)
   set(exe_target ${PROJECT_NAME}.elf)
-
-  spaces2list(${MAIN_SRCS})
+ 
+  spaces2list(MAIN_SRCS)
   add_executable(${exe_target} "${MAIN_SRCS}")
 
   add_map_file(${exe_target})
+
 endfunction(idf_add_executable)
 
 
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index d7ec6f4c3..6d93ab192 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -44,9 +44,23 @@ function(kconfig_process_config)
     endif()
   endforeach(dir ${COMPONENT_PATHS})
 
+  if(EXISTS ${SDKCONFIG}.defaults)
+    set(defaults_arg --defaults "${SDKCONFIG}.defaults")
+  endif()
+
+  set(confgen_basecommand
+    ${PYTHON} ${IDF_PATH}/tools/kconfig_new/confgen.py
+    --kconfig ${ROOT_KCONFIG}
+    --config ${SDKCONFIG}
+    ${defaults_arg}
+    --create-config-if-missing
+    --env "COMPONENT_KCONFIGS=${kconfigs}"
+    --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}")
+
   # Generate the menuconfig target (uses C-based mconf tool)
   add_custom_target(menuconfig
     DEPENDS mconf
+    COMMAND ${confgen_basecommand} --output config ${SDKCONFIG}  # create any missing config file, with defaults if necessary
     COMMAND ${CMAKE_COMMAND} -E env
                 "COMPONENT_KCONFIGS=${kconfigs}"
                 "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
@@ -59,12 +73,7 @@ function(kconfig_process_config)
   # makes sdkconfig.h and skdconfig.cmake
   #
   # This happens at cmake runtime not during the build
-  execute_process(COMMAND python ${IDF_PATH}/tools/kconfig_new/confgen.py
-    --kconfig ${ROOT_KCONFIG}
-    --config ${SDKCONFIG}
-    --create-config-if-missing
-    --env "COMPONENT_KCONFIGS=${kconfigs}"
-    --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+  execute_process(COMMAND ${confgen_basecommand}
     --output header ${SDKCONFIG_HEADER}
     --output cmake ${SDKCONFIG_CMAKE})
 
diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
index ca5ee6390..00c92c3b6 100755
--- a/tools/kconfig_new/confgen.py
+++ b/tools/kconfig_new/confgen.py
@@ -32,13 +32,18 @@ import kconfiglib
 __version__ = "0.1"
 
 def main():
-    parser = argparse.ArgumentParser(description='confgen.py v%s - Config Generation Tool' % __version__, prog='conftool')
+    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')
@@ -73,13 +78,20 @@ def main():
 
     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)
-        else:
+        elif args.default is None:
             raise RuntimeError("Config file not found: %s" % args.config)
 
         for output_type, filename in args.output:

From 0bdc12256ef7c35bb771aa7fa3124935b56aa5e6 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 22 Jan 2018 15:16:01 +1100
Subject: [PATCH 018/112] cmake: Add "size" target, update idf_size.py for
 different linker behaviour

---
 tools/cmake/idf_functions.cmake | 15 +++++++++++++++
 tools/idf_size.py               | 19 +++++++++++++------
 2 files changed, 28 insertions(+), 6 deletions(-)

diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 101f8e10f..c6e2233b3 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -128,4 +128,19 @@ function(add_map_file exe_target)
   set(mapfile "${basename}.map")
   target_link_libraries(${exe_target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
   set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
+
+  # add size targets, depend on map file, run idf_size.py
+  add_custom_target(size
+    DEPENDS ${exe_target}
+    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py ${mapfile}
+    )
+  add_custom_target(size-files
+    DEPENDS ${exe_target}
+    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --files ${mapfile}
+    )
+  add_custom_target(size-components
+    DEPENDS ${exe_target}
+    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --archives ${mapfile}
+    )
+
 endfunction(add_map_file)
diff --git a/tools/idf_size.py b/tools/idf_size.py
index 1893082ff..d67cfa25a 100755
--- a/tools/idf_size.py
+++ b/tools/idf_size.py
@@ -82,7 +82,6 @@ def load_sections(map_file):
     is a dict with details about this section, including a "sources" key which holds a list of source file line information for each symbol linked into the section.
     """
     scan_to_header(map_file, "Linker script and memory map")
-    scan_to_header(map_file, "END GROUP")
     sections = {}
     section = None
     sym_backup = None
@@ -102,16 +101,24 @@ def load_sections(map_file):
 
         # source file line, ie
         # 0x0000000040080400       0xa4 /home/gus/esp/32/idf/examples/get-started/hello_world/build/esp32/libesp32.a(cpu_start.o)
-        RE_SOURCE_LINE = r"\s*(?P<sym_name>\S*).* +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<archive>.+\.a)\((?P<object_file>.+\.o)\)"
-
-        m = re.match(RE_SOURCE_LINE, line, re.M)
+        RE_SOURCE_LINE = r"\s*(?P<sym_name>\S*).* +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<archive>.+\.a)\((?P<object_file>.+\.ob?j?)\)"
+        m = re.match(RE_SOURCE_LINE, line)
+        if not m:
+            # cmake build system links some object files directly, not part of any archive
+            RE_SOURCE_LINE = r".*? +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<object_file>.+\.ob?j?)"
+            m = re.match(RE_SOURCE_LINE, line)
         if section is not None and m is not None:  # input source file details
             sym_name = m.group("sym_name") if len(m.group("sym_name")) > 0 else sym_backup
+            try:
+                archive = m.group("archive")
+            except IndexError:
+                archive = "(exe)"
+
             source = {
                 "size" : int(m.group("size"), 16),
                 "address" : int(m.group("address"), 16),
-                "archive" : os.path.basename(m.group("archive")),
-                "object_file" : m.group("object_file"),
+                "archive" : os.path.basename(archive)),
+                "object_file" : os.path.basename(m.group("object_file")),
                 "sym_name" : sym_name,
             }
             source["file"] = "%s:%s" % (source["archive"], source["object_file"])

From cb99531d15e4c409d43e033c9111ef83e5c1d218 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 1 Feb 2018 17:45:41 +0800
Subject: [PATCH 019/112] cmake: Generate PHY init data partition as part of
 the build

---
 components/esp32/CMakeLists.txt             | 16 +++++++++++++++-
 components/esp32/phy_init_data.h            |  5 ++++-
 components/esptool_py/CMakeLists.txt        |  9 +++++++++
 components/esptool_py/flash_project_args.in |  3 +++
 components/partition_table/CMakeLists.txt   |  8 ++++----
 toolchain.cmake                             |  1 +
 tools/cmake/utilities.cmake                 | 19 +++++++++++++++++++
 7 files changed, 55 insertions(+), 6 deletions(-)
 create mode 100644 components/esptool_py/flash_project_args.in

diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index cf0dff1f0..a67ab89d1 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -58,4 +58,18 @@ else()
   add_custom_target(esp32_linker_script DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld)
   add_dependencies(esp32 esp32_linker_script)
 
-endif()
+  if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+    set(PHY_INIT_DATA_BIN phy_init_data.bin)
+
+    # To get the phy_init_data.bin file, compile phy_init_data.h as a C file and then objcopy the object file to a raw binary
+    add_custom_command(
+      OUTPUT ${PHY_INIT_DATA_BIN}
+      DEPENDS ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
+      COMMAND ${CMAKE_C_COMPILER} -x c -c -o phy_init_data.obj -I ${CMAKE_CURRENT_LIST_DIR} -I ${CMAKE_CURRENT_LIST_DIR}/include -I ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
+      COMMAND ${CMAKE_OBJCOPY} -O binary phy_init_data.obj ${PHY_INIT_DATA_BIN}
+      )
+    add_custom_target(phy_init_data ALL DEPENDS ${PHY_INIT_DATA_BIN})
+
+  endif(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+
+endif(BOOTLOADER_BUILD)
diff --git a/components/esp32/phy_init_data.h b/components/esp32/phy_init_data.h
index d09bbdd9c..9213020ca 100644
--- a/components/esp32/phy_init_data.h
+++ b/components/esp32/phy_init_data.h
@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-#pragma once
+#ifndef PHY_INIT_DATA_H
+#define PHY_INIT_DATA_H /* don't use #pragma once here, we compile this file sometimes */
 #include "esp_phy_init.h"
 #include "sdkconfig.h"
 
@@ -138,3 +139,5 @@ static const esp_phy_init_data_t phy_init_data= { {
 
 static const char phy_init_magic_post[] = PHY_INIT_MAGIC;
 
+#endif /* PHY_INIT_DATA_H */
+
diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
index bdd55ceea..f5f5514ee 100644
--- a/components/esptool_py/CMakeLists.txt
+++ b/components/esptool_py/CMakeLists.txt
@@ -1 +1,10 @@
 register_config_only_component()
+
+configure_file(
+  "${CMAKE_CURRENT_LIST_DIR}/flash_project_args.in"
+  "${CMAKE_BINARY_DIR}/flash_project_args"
+  )
+if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+  file_append_line(${CMAKE_BINARY_DIR}/flash_project_args
+    "${CONFIG_PHY_DATA_OFFSET} esp32/phy_init_data.bin")
+endif()
diff --git a/components/esptool_py/flash_project_args.in b/components/esptool_py/flash_project_args.in
new file mode 100644
index 000000000..1733f5753
--- /dev/null
+++ b/components/esptool_py/flash_project_args.in
@@ -0,0 +1,3 @@
+0x1000 bootloader/bootloader.bin
+0x8000 partition_table/partition-table.bin
+${CONFIG_APP_OFFSET} ${PROJECT_NAME}.elf
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index f39408806..c0b2a3833 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -11,12 +11,12 @@ else()
 endif()
 
 if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
-  set(unsigned_partition_bin "partition-unsigned.bin")
-  set(final_partition_bin "partition.bin")
+  set(unsigned_partition_bin "partition-table-unsigned.bin")
+  set(final_partition_bin "partition-table.bin")
   set(final_partition_target "sign_partition_table")
 else()
-  set(unsigned_partition_bin "partition.bin")
-  set(final_partition_bin "partition.bin")
+  set(unsigned_partition_bin "partition-table.bin")
+  set(final_partition_bin "partition-table.bin")
   set(final_partition_target "build_partition_table")
 endif()
 
diff --git a/toolchain.cmake b/toolchain.cmake
index cecba78af..ccf6eab86 100644
--- a/toolchain.cmake
+++ b/toolchain.cmake
@@ -3,5 +3,6 @@ set(CMAKE_SYSTEM_NAME Generic)
 set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
 set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
 set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
+set(CMAKE_OBJCOPY xtensa-esp32-elf-objcopy)
 
 set(CMAKE_EXE_LINKER_FLAGS "-nostdlib" CACHE STRING "Linker Base Flags")
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 5c3bac996..759b559a3 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -127,3 +127,22 @@ macro(include_if_exists path)
     include("${path}")
   endif()
 endmacro(include_if_exists)
+
+# Append a single line to the file specified
+# The line ending is determined by the host OS
+function(file_append_line file line)
+  if(ENV{MSYSTEM} OR CMAKE_HOST_WIN32)
+    set(line_ending "\r\n")
+  else() # unix
+    set(line_ending "\n")
+  endif()
+  file(READ ${file} existing)
+  string(FIND ${existing} ${line_ending} last_newline REVERSE)
+  string(LENGTH ${existing} length)
+  math(EXPR length "${length}-1")
+  if(NOT length EQUAL last_newline) # file doesn't end with a newline
+    file(APPEND "${file}" "${line_ending}")
+  endif()
+  file(APPEND "${file}" "${line}${line_ending}")
+endfunction()
+

From 7eaf2f4bdb9803eb1062824136fb1e711fa4bfd5 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 6 Feb 2018 18:03:41 +0800
Subject: [PATCH 020/112] kconfig: Allow out of tree building, build under
 cmake build directory

---
 tools/cmake/kconfig.cmake | 15 ++++++++-------
 tools/kconfig/Makefile    | 34 +++++++++++++++++++++++++---------
 2 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 6d93ab192..ac699598c 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -1,7 +1,7 @@
 include(ExternalProject)
 
 macro(kconfig_set_variables)
-  set(MCONF ${IDF_PATH}/tools/kconfig/mconf)
+  set(MCONF kconfig_bin/mconf)
 
   set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
   set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
@@ -10,19 +10,20 @@ macro(kconfig_set_variables)
   set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
 endmacro()
 
-# Use the existing Makefile to build mconf when needed
+# Use the existing Makefile to build mconf (out of tree) when needed
 #
-# TODO: replace this with something more Windows-friendly
+# TODO: Find a solution on Windows
 ExternalProject_Add(mconf
   SOURCE_DIR ${IDF_PATH}/tools/kconfig
   CONFIGURE_COMMAND ""
-  BUILD_IN_SOURCE 1
-  BUILD_COMMAND make mconf
-  BUILD_BYPRODUCTS ${MCONF}
+  BINARY_DIR "kconfig_bin"
+  BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
+  BUILD_BYPRODUCTS "kconfig_bin" ${MCONF}
   INSTALL_COMMAND ""
   EXCLUDE_FROM_ALL 1
   )
 
+
 # Find all Kconfig files for all components
 function(kconfig_process_config)
   file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
@@ -65,7 +66,7 @@ function(kconfig_process_config)
                 "COMPONENT_KCONFIGS=${kconfigs}"
                 "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
                 "KCONFIG_CONFIG=${SDKCONFIG}"
-                ${IDF_PATH}/tools/kconfig/mconf ${ROOT_KCONFIG}
+                ${MCONF} ${ROOT_KCONFIG}
     VERBATIM
     USES_TERMINAL)
 
diff --git a/tools/kconfig/Makefile b/tools/kconfig/Makefile
index 2454e47af..c8a56abdd 100644
--- a/tools/kconfig/Makefile
+++ b/tools/kconfig/Makefile
@@ -2,6 +2,10 @@
 # Kernel configuration targets
 # These targets are used from top-level makefile
 
+# SRCDIR is kconfig source dir, allows for out-of-tree builds
+# if building in tree, SRCDIR==build dir
+SRCDIR := $(abspath $(dir $(firstword $(MAKEFILE_LIST))))
+
 PHONY += xconfig gconfig menuconfig config silentoldconfig \
 	localmodconfig localyesconfig clean
 
@@ -156,13 +160,22 @@ help:
 	@echo  '  tinyconfig	  - Configure the tiniest possible kernel'
 
 # lxdialog stuff
-check-lxdialog  := lxdialog/check-lxdialog.sh
+check-lxdialog  := $(SRCDIR)/lxdialog/check-lxdialog.sh
 
 # Use recursively expanded variables so we do not call gcc unless
 # we really need to do so. (Do not call gcc as part of make mrproper)
 CFLAGS += $(shell $(CONFIG_SHELL) $(check-lxdialog) -ccflags) \
                     -DLOCALE -MD
 
+%.o: $(SRCDIR)/%.c
+	$(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
+
+lxdialog/%.o: $(SRCDIR)/lxdialog/%.c
+	$(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
+
+%.o: %.c
+	$(CC) -I $(SRCDIR) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
+
 # ===========================================================================
 # Shared Makefile for the various kconfig executables:
 # conf:	  Used for defconfig, oldconfig and related targets
@@ -199,9 +212,12 @@ clean-files += $(all-objs) $(all-deps) conf mconf
 # Check that we have the required ncurses stuff installed for lxdialog (menuconfig)
 PHONY += dochecklxdialog
 $(addprefix ,$(lxdialog)): dochecklxdialog
-dochecklxdialog:
+dochecklxdialog: lxdialog
 	$(CONFIG_SHELL) $(check-lxdialog) -check $(CC) $(CFLAGS) $(LOADLIBES_mconf)
 
+lxdialog:
+	mkdir -p lxdialog
+
 always := dochecklxdialog
 
 # Add environment specific flags
@@ -308,7 +324,7 @@ gconf.glade.h: gconf.glade
 	gconf.glade
 
 
-mconf: $(mconf-objs)
+mconf: lxdialog $(mconf-objs)
 	$(CC) -o $@ $(mconf-objs) $(LOADLIBES_mconf)
 
 conf: $(conf-objs)
@@ -316,15 +332,15 @@ conf: $(conf-objs)
 
 zconf.tab.c: zconf.lex.c
 
-zconf.lex.c: zconf.l
-	flex -L -P zconf -o zconf.lex.c zconf.l
+zconf.lex.c: $(SRCDIR)/zconf.l
+	flex -L -P zconf -o zconf.lex.c $<
 
-zconf.hash.c: zconf.gperf
+zconf.hash.c: $(SRCDIR)/zconf.gperf
 # strip CRs on Windows systems where gperf will otherwise barf on them
-	sed -E "s/\\x0D$$//" zconf.gperf | gperf -t --output-file zconf.hash.c -a -C -E -g -k '1,3,$$' -p -t
+	sed -E "s/\\x0D$$//" $< | gperf -t --output-file zconf.hash.c -a -C -E -g -k '1,3,$$' -p -t
 
-zconf.tab.c: zconf.y
-	bison -t -l -p zconf -o zconf.tab.c zconf.y
+zconf.tab.c: $(SRCDIR)/zconf.y
+	bison -t -l -p zconf -o zconf.tab.c $<
 
 clean:
 	rm -f $(clean-files)

From efb59289345cebf01c3b1e375a4d30b083576967 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 23 Jan 2018 17:08:28 +1100
Subject: [PATCH 021/112] idf.py build & flash tool

Generate flasher args files & .json project info file as part of cmake build
---
 Kconfig                                       |   3 +
 components/esp32/CMakeLists.txt               |   2 +
 components/esptool_py/CMakeLists.txt          |  11 +-
 components/esptool_py/flash_app_args.in       |   4 +
 .../esptool_py/flash_bootloader_args.in       |   4 +
 .../esptool_py/flash_partition_table_args.in  |   4 +
 components/esptool_py/flash_project_args.in   |   6 +-
 components/esptool_py/project_include.cmake   |  47 +--
 toolchain.cmake                               |   1 -
 tools/cmake/components.cmake                  |   2 +-
 tools/cmake/idf_functions.cmake               |  17 +
 tools/cmake/kconfig.cmake                     |  26 +-
 tools/cmake/project.cmake                     |   9 +-
 tools/cmake/project_description.json.in       |  17 +
 tools/idf.py                                  | 331 ++++++++++++++++++
 tools/kconfig_new/confgen.py                  |  25 +-
 16 files changed, 464 insertions(+), 45 deletions(-)
 create mode 100644 components/esptool_py/flash_app_args.in
 create mode 100644 components/esptool_py/flash_bootloader_args.in
 create mode 100644 components/esptool_py/flash_partition_table_args.in
 create mode 100644 tools/cmake/project_description.json.in
 create mode 100755 tools/idf.py

diff --git a/Kconfig b/Kconfig
index b1498870a..ac8a1db95 100644
--- a/Kconfig
+++ b/Kconfig
@@ -20,6 +20,9 @@ config PYTHON
         The executable name/path that is used to run python. On some systems Python 2.x
         may need to be invoked as python2.
 
+        (Note: This option is used with the GNU Make build system only, not idf.py
+        or CMake-based builds.)
+
 config MAKE_WARN_UNDEFINED_VARIABLES
     bool "'make' warns on undefined variables"
     default "y"
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index a67ab89d1..963f8802b 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -41,6 +41,7 @@ else()
 
   target_link_libraries(esp32 "${CMAKE_CURRENT_SOURCE_DIR}/libhal.a")
   target_link_libraries(esp32 gcc)
+  target_link_libraries(esp32 "-u call_user_start_cpu0")
 
   #ld_include_panic_highint_hdl is added as an undefined symbol because otherwise the
 #linker will ignore panic_highint_hdl.S as it has no other files depending on any
@@ -69,6 +70,7 @@ else()
       COMMAND ${CMAKE_OBJCOPY} -O binary phy_init_data.obj ${PHY_INIT_DATA_BIN}
       )
     add_custom_target(phy_init_data ALL DEPENDS ${PHY_INIT_DATA_BIN})
+    add_dependencies(flash phy_init_data)
 
   endif(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
 
diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
index f5f5514ee..d8d64344c 100644
--- a/components/esptool_py/CMakeLists.txt
+++ b/components/esptool_py/CMakeLists.txt
@@ -1,10 +1,9 @@
 register_config_only_component()
 
+# Generate pre-canned flasher args files suitable for passing to esptool.py
+foreach(part project app bootloader)
 configure_file(
-  "${CMAKE_CURRENT_LIST_DIR}/flash_project_args.in"
-  "${CMAKE_BINARY_DIR}/flash_project_args"
+  "${CMAKE_CURRENT_LIST_DIR}/flash_${part}_args.in"
+  "${CMAKE_BINARY_DIR}/flash_${part}_args"
   )
-if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
-  file_append_line(${CMAKE_BINARY_DIR}/flash_project_args
-    "${CONFIG_PHY_DATA_OFFSET} esp32/phy_init_data.bin")
-endif()
+endforeach()
diff --git a/components/esptool_py/flash_app_args.in b/components/esptool_py/flash_app_args.in
new file mode 100644
index 000000000..7cc24a638
--- /dev/null
+++ b/components/esptool_py/flash_app_args.in
@@ -0,0 +1,4 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
+${CONFIG_APP_OFFSET} ${PROJECT_NAME}.bin
diff --git a/components/esptool_py/flash_bootloader_args.in b/components/esptool_py/flash_bootloader_args.in
new file mode 100644
index 000000000..ac19a6d81
--- /dev/null
+++ b/components/esptool_py/flash_bootloader_args.in
@@ -0,0 +1,4 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
+0x1000 bootloader/bootloader.bin
diff --git a/components/esptool_py/flash_partition_table_args.in b/components/esptool_py/flash_partition_table_args.in
new file mode 100644
index 000000000..f5bbe084c
--- /dev/null
+++ b/components/esptool_py/flash_partition_table_args.in
@@ -0,0 +1,4 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
+0x8000 partition_table/partition-table.bin
diff --git a/components/esptool_py/flash_project_args.in b/components/esptool_py/flash_project_args.in
index 1733f5753..70edf4fae 100644
--- a/components/esptool_py/flash_project_args.in
+++ b/components/esptool_py/flash_project_args.in
@@ -1,3 +1,7 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
 0x1000 bootloader/bootloader.bin
 0x8000 partition_table/partition-table.bin
-${CONFIG_APP_OFFSET} ${PROJECT_NAME}.elf
+${CONFIG_APP_OFFSET} ${PROJECT_NAME}.bin
+${PHY_PARTITION_OFFSET} ${PHY_PARTITION_BIN_FILE}
diff --git a/components/esptool_py/project_include.cmake b/components/esptool_py/project_include.cmake
index 52fc289ee..04efbb7e7 100644
--- a/components/esptool_py/project_include.cmake
+++ b/components/esptool_py/project_include.cmake
@@ -1,48 +1,49 @@
 # Set some global esptool.py variables
+#
+# Many of these are read when generating flash_app_args & flash_project_args
 set(ESPTOOLPY "${PYTHON}" "${CMAKE_CURRENT_LIST_DIR}/esptool/esptool.py" --chip esp32)
 set(ESPSECUREPY "${PYTHON}" "${CMAKE_CURRENT_LIST_DIR}/esptool/espsecure.py")
 
-set(ESPPORT $ENV{ESPPORT})
-if(NOT ESPPORT)
-  set(ESPPORT ${CONFIG_ESPTOOLPY_PORT})
-endif()
-
-set(ESPBAUD $ENV{ESPPORT})
-if(NOT ESPBAUD)
-  set(ESPPORT ${CONFIG_ESPTOOLPY_PORT})
-endif()
-
 set(ESPFLASHMODE ${CONFIG_ESPTOOLPY_FLASHMODE})
 set(ESPFLASHFREQ ${CONFIG_ESPTOOLPY_FLASHFREQ})
 set(ESPFLASHSIZE ${CONFIG_ESPTOOLPY_FLASHSIZE})
 
 set(ESPTOOLPY_SERIAL "${ESPTOOLPY}" --port "${ESPPORT}" --baud ${ESPBAUD})
 
-if(CONFIG_ESPTOOLPY_FLASHSIZE_DETECT)
-  set(flashsize_arg detect)
-else()
-  set(flashsize_arg ${ESPFLASHSIZE})
-endif()
-
 set(ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS --flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${ESPFLASHSIZE})
 
-set(ESPTOOLPY_WRITE_FLASH_OPTIONS --flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${flashsize_Arg})
+if(CONFIG_ESPTOOLPY_FLASHSIZE_DETECT)
+  # Set ESPFLASHSIZE to 'detect' *after* elf2image options are generated,
+  # as elf2image can't have 'detect' as an option...
+  set(ESPFLASHSIZE detect)
+endif()
 
-set(ESPTOOLPY_WRITE_FLASH ${ESPTOOLPY_SERIAL} write_flash ${ESPTOOLPY_WRITE_FLASH_OPTIONS})
+# Set variables if the PHY data partition is in the flash
+if (CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+  set(PHY_PARTITION_OFFSET   ${CONFIG_PHY_DATA_OFFSET})
+  set(PHY_PARTITION_BIN_FILE "esp32/phy_init_data.bin")
+endif()
 
 #
-# Add 'binary' target - generates with elf2image
+# Add 'app.bin' target - generates with elf2image
 #
 add_custom_command(OUTPUT "${PROJECT_NAME}.bin"
   COMMAND ${ESPTOOLPY} elf2image ${ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS} -o "${PROJECT_NAME}.bin" "${PROJECT_NAME}.elf"
   DEPENDS ${PROJECT_NAME}.elf
   VERBATIM
   )
-add_custom_target(binary ALL DEPENDS "${PROJECT_NAME}.bin")
+add_custom_target(app ALL DEPENDS "${PROJECT_NAME}.bin")
 
 #
 # Add 'flash' target - not all build systems can run this directly
 #
-add_custom_target(flash DEPENDS binary partition_table bootloader_subproject)
-# TODO: this target should call "idftool" not esptool directly, so it can
-# override things (port, baud, etc) at runtime not configure time
+function(esptool_py_custom_target target_name flasher_filename dependencies)
+  add_custom_target(${target_name} DEPENDS ${dependencies}
+    COMMAND ${ESPTOOLPY} -p ${CONFIG_ESPTOOLPY_PORT} -b ${CONFIG_ESPTOOLPY_BAUD} write_flash @flash_${flasher_filename}_args
+    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+    )
+endfunction()
+
+esptool_py_custom_target(flash project "app;partition_table;bootloader")
+esptool_py_custom_target(app-flash app "app")
+esptool_py_custom_target(bootloader-flash bootloader "bootloader")
diff --git a/toolchain.cmake b/toolchain.cmake
index ccf6eab86..cecba78af 100644
--- a/toolchain.cmake
+++ b/toolchain.cmake
@@ -3,6 +3,5 @@ set(CMAKE_SYSTEM_NAME Generic)
 set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
 set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
 set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
-set(CMAKE_OBJCOPY xtensa-esp32-elf-objcopy)
 
 set(CMAKE_EXE_LINKER_FLAGS "-nostdlib" CACHE STRING "Linker Base Flags")
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index bd9481b48..6e3d4ee51 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -65,7 +65,7 @@ function(register_component)
         message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' does not exist")
       endif()
 
-      file(GLOB matches "${abs_dir}/*.[c|S]" "${abs_dir}/*.cpp")
+      file(GLOB matches "${abs_dir}/*.c" "${abs_dir}/*.cpp" "${abs_dir}/*.S")
       if(matches)
         list(SORT matches)
         set(COMPONENT_SRCS "${COMPONENT_SRCS};${matches}")
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index c6e2233b3..c6ecd5ed5 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -22,6 +22,12 @@ macro(idf_set_global_variables)
   # Tell cmake to drop executables in the top-level build dir
   set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}")
 
+  # cmake cross-toolchain doesn't include any gcc binutils names
+  set(CMAKE_OBJCOPY xtensa-esp32-elf-objcopy)
+
+  # path to idf.py tool
+  set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
+
 endmacro()
 
 # Add all the IDF global compiler & preprocessor options
@@ -117,6 +123,8 @@ function(idf_add_executable)
 
   add_map_file(${exe_target})
 
+  add_flasher_argfile(${exe_target})
+
 endfunction(idf_add_executable)
 
 
@@ -144,3 +152,12 @@ function(add_map_file exe_target)
     )
 
 endfunction(add_map_file)
+
+# add_flasher_argfile
+#
+# Add argument file(s) for flashing the app, and for flashing the whole system
+function(add_flasher_argfile)
+
+  
+
+endfunction(add_flasher_argfile)
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index ac699598c..9f4d4ffa4 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -6,19 +6,20 @@ macro(kconfig_set_variables)
   set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
   set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
   set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
+  set(SDKCONFIG_JSON ${CMAKE_BINARY_DIR}/sdkconfig.json)
 
   set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
 endmacro()
 
 # Use the existing Makefile to build mconf (out of tree) when needed
 #
-# TODO: Find a solution on Windows
+# TODO: Download(?) a prebuilt mingw mconf on Windows
 ExternalProject_Add(mconf
   SOURCE_DIR ${IDF_PATH}/tools/kconfig
   CONFIGURE_COMMAND ""
   BINARY_DIR "kconfig_bin"
   BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
-  BUILD_BYPRODUCTS "kconfig_bin" ${MCONF}
+  BUILD_BYPRODUCTS ${MCONF}
   INSTALL_COMMAND ""
   EXCLUDE_FROM_ALL 1
   )
@@ -73,21 +74,28 @@ function(kconfig_process_config)
   # Generate configuration output via confgen.py
   # makes sdkconfig.h and skdconfig.cmake
   #
-  # This happens at cmake runtime not during the build
+  # This happens during the cmake run not during the build
   execute_process(COMMAND ${confgen_basecommand}
     --output header ${SDKCONFIG_HEADER}
-    --output cmake ${SDKCONFIG_CMAKE})
+    --output cmake ${SDKCONFIG_CMAKE}
+    --output json ${SDKCONFIG_JSON}
+	RESULT_VARIABLE config_result)
+  if(config_result)
+	message(FATAL_ERROR "Failed to run confgen.py (${confgen_basecommand}). Error ${config_result}")
+  endif()
 
   # When sdkconfig file changes in the future, trigger a cmake run
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG})
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG}")
 
   # Ditto if either of the generated files are missing/modified (this is a bit irritating as it means
   # you can't edit these manually without them being regenerated, but I don't know of a better way...)
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG_HEADER})
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${SDKCONFIG_CMAKE})
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_HEADER}")
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_CMAKE}")
 
   # Or if the config generation tool changes
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${IDF_PATH}/tools/kconfig_new/confgen.py)
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${IDF_PATH}/tools/kconfig_new/kconfiglib.py)
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/confgen.py")
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/kconfiglib.py")
+
+  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${SDKCONFIG_HEADER}" "${SDKCONFIG_CMAKE}")
 
 endfunction()
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index e8e3cc7ca..b23f39d73 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -22,6 +22,8 @@ include(kconfig)
 include(git_submodules)
 include(idf_functions)
 
+set_default(PYTHON "python")
+
 # Verify the environment is configured correctly
 idf_verify_environment()
 
@@ -38,8 +40,6 @@ kconfig_process_config()
 # Include sdkconfig.cmake so rest of the build knows the configuration
 include(${SDKCONFIG_CMAKE})
 
-set(PYTHON "${CONFIG_PYTHON}")
-
 # Add some idf-wide definitions
 idf_set_global_compiler_options()
 
@@ -49,7 +49,6 @@ git_describe(GIT_REVISION)
 add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
 git_submodule_check("${IDF_PATH}")
 
-
 # Include any top-level project_include.cmake files from components
 foreach(component ${COMPONENT_PATHS})
   include_if_exists("${component}/project_include.cmake")
@@ -68,6 +67,10 @@ endforeach()
 #
 idf_add_executable()
 
+# Write project description JSON file
+configure_file("${CMAKE_CURRENT_LIST_DIR}/project_description.json.in"
+  "${CMAKE_BINARY_DIR}/project_description.json")
+
 #
 # Finish component registration (add cross-dependencies, make
 # executable dependent on all components)
diff --git a/tools/cmake/project_description.json.in b/tools/cmake/project_description.json.in
new file mode 100644
index 000000000..21bbb3c87
--- /dev/null
+++ b/tools/cmake/project_description.json.in
@@ -0,0 +1,17 @@
+{
+    "project_name":       "${PROJECT_NAME}",
+    "project_path":       "${PROJECT_PATH}",
+    "build_dir":          "${CMAKE_BINARY_DIR}",
+    "config_file":        "${SDKCONFIG}",
+    "app_elf":            "${PROJECT_NAME}.elf",
+    "app_bin":            "${PROJECT_NAME}.bin",
+    "git_revision":       "${GIT_REVISION}",
+    "project_binaries":  {
+        "bootloader":        [ "0x1000", "bootloader/bootloader.bin" ],
+        "partition_table":   [ "0x8000", "partition_table/partition-table.bin" ],
+        "app":               [ "${CONFIG_APP_OFFSET}", "${PROJECT_NAME}.bin" ],
+        "phy_data":          [ "${PHY_PARTITION_OFFSET}", "${PHY_PARTITION_BIN_FILE}" ]
+    },
+    "phy_data_partition": "${CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION}",
+    "monitor_baud" : "${CONFIG_MONITOR_BAUD}"
+}
diff --git a/tools/idf.py b/tools/idf.py
new file mode 100755
index 000000000..4b3ebc371
--- /dev/null
+++ b/tools/idf.py
@@ -0,0 +1,331 @@
+#!/usr/bin/env python
+#
+# 'idf.py' is a top-level config/build command line tool for ESP-IDF
+#
+# You don't have to use idf.py, you can use cmake directly
+# (or use cmake in an IDE)
+#
+#
+#
+# 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 sys
+import argparse
+import os
+import os.path
+import subprocess
+import multiprocessing
+import re
+import shutil
+import json
+
+# Use this Python interpreter for any subprocesses we launch
+PYTHON=sys.executable
+
+# note: os.environ changes don't automatically propagate to child processes,
+# you have to pass this in explicitly
+os.environ["PYTHON"]=sys.executable
+
+# Make flavors, across the various kinds of Windows environments & POSIX...
+if "MSYSTEM" in os.environ:  # MSYS
+    MAKE_CMD = "make"
+    MAKE_GENERATOR = "MSYS Makefiles"
+elif os.name == 'nt':  # other Windows
+    MAKE_CMD = "mingw32-make"
+    MAKE_GENERATOR = "MinGW Makefiles"
+else:
+    MAKE_CMD = "make"
+    MAKE_GENERATOR = "Unix Makefiles"
+
+GENERATORS = [
+    # ('generator name', 'build command line', 'version command line')
+    ("Ninja", [ "ninja" ], [ "ninja", "--version" ]),
+    (MAKE_GENERATOR, [ MAKE_CMD, "-j", str(multiprocessing.cpu_count()+2) ], [ "make", "--version" ]),
+    ]
+GENERATOR_CMDS = dict( (a[0], a[1]) for a in GENERATORS )
+
+def check_environment():
+    """
+    Verify the environment contains the top-level tools we need to operate
+
+    (cmake will check a lot of other things)
+    """
+    if not executable_exists(["cmake", "--version"]):
+        raise RuntimeError("'cmake' must be available on the PATH to use idf.py")
+    # find the directory idf.py is in, then the parent directory of this, and assume this is IDF_PATH
+    detected_idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), ".."))
+    if "IDF_PATH" in os.environ:
+        set_idf_path = os.path.realpath(os.environ["IDF_PATH"])
+        if set_idf_path != detected_idf_path:
+            print("WARNING: IDF_PATH environment variable is set to %s but idf.py path indicates IDF directory %s. Using the environment variable directory, but results may be unexpected..."
+                  % (set_idf_path, detected_idf_path))
+    else:
+        os.environ["IDF_PATH"] = detected_idf_path
+
+def executable_exists(args):
+    try:
+        subprocess.check_output(args)
+        return True
+    except:
+        return False
+
+def detect_cmake_generator():
+    """
+    Find the default cmake generator, if none was specified. Raises an exception if no valid generator is found.
+    """
+    for (generator, _, version_check) in GENERATORS:
+        if executable_exists(version_check):
+            return generator
+    raise RuntimeError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")
+
+def _ensure_build_directory(args):
+    """Check the build directory exists and that cmake has been run there.
+
+    If this isn't the case, create the build directory (if necessary) and
+    do an initial cmake run to configure it.
+
+    This function will also check args.generator parameter. If the parameter is incompatible with
+    the build directory, an error is raised. If the parameter is None, this function will set it to
+    an auto-detected default generator or to the value already configured in the build directory.
+    """
+    project_dir = args.project_dir
+    # Verify the project directory
+    if not os.path.isdir(project_dir):
+        if not os.path.exists(project_dir):
+            raise RuntimeError("Project directory %s does not exist")
+        else:
+            raise RuntimeError("%s must be a project directory")
+    if not os.path.exists(os.path.join(project_dir, "CMakeLists.txt")):
+        raise RuntimeError("CMakeLists.txt not found in project directory %s" % project_dir)
+
+    # Verify/create the build directory
+    build_dir = args.build_dir
+    if not os.path.isdir(build_dir):
+        os.mkdir(build_dir)
+    cache_path = os.path.join(build_dir, "CMakeCache.txt")
+    if not os.path.exists(cache_path):
+        if args.generator is None:
+            args.generator = detect_cmake_generator()
+        print("Running cmake...")
+        # Note: we explicitly pass in os.environ here, as we may have set IDF_PATH there during startup
+        try:
+            subprocess.check_call(["cmake", "-G", args.generator, project_dir], env=os.environ, cwd=args.build_dir)
+        except:
+            if os.path.exists(cache_path):  # don't allow partial CMakeCache.txt files, to keep the "should I run cmake?" logic simple
+                os.remove(cache_path)
+            raise
+
+    # Learn some things from the CMakeCache.txt file in the build directory
+    cache = parse_cmakecache(cache_path)
+    try:
+        generator = cache["CMAKE_GENERATOR"]
+    except KeyError:
+        generator = detect_cmake_generator()
+    if args.generator is None:
+        args.generator = generator  # reuse the previously configured generator, if none was given
+    if generator != args.generator:
+        raise RuntimeError("Build is configured for generator '%s' not '%s'. Run 'idf.py fullclean' to start again."
+                           % (generator, args.generator))
+
+    try:
+        home_dir = cache["CMAKE_HOME_DIRECTORY"]
+        if os.path.realpath(home_dir) != os.path.realpath(project_dir):
+            raise RuntimeError("Build directory '%s' configured for project '%s' not '%s'. Run 'idf.py fullclean' to start again."
+                            % (build_dir, os.path.realpath(home_dir), os.path.realpath(project_dir)))
+    except KeyError:
+        pass  # if cmake failed part way, CMAKE_HOME_DIRECTORY may not be set yet
+
+
+def parse_cmakecache(path):
+    """
+    Parse the CMakeCache file at 'path'.
+
+    Returns a dict of name:value.
+
+    CMakeCache entries also each have a "type", but this is currently ignored.
+    """
+    result = {}
+    with open(path) as f:
+        for line in f:
+            # cmake cache lines look like: CMAKE_CXX_FLAGS_DEBUG:STRING=-g
+            # groups are name, type, value
+            m = re.match(r"^([^#/:=]+):([^:=]+)=(.+)\n$", line)
+            if m:
+               result[m.group(1)] = m.group(3)
+    return result
+
+def build_target(target_name, args):
+    """
+    Execute the target build system to build target 'target_name'
+
+    Calls _ensure_build_directory() which will run cmake to generate a build
+    directory (with the specified generator) as needed.
+    """
+    _ensure_build_directory(args)
+    generator_cmd = GENERATOR_CMDS[args.generator]
+    print("Running '%s %s' in %s..." % (generator_cmd, target_name, args.build_dir))
+    subprocess.check_call(generator_cmd + [target_name], cwd=args.build_dir)
+
+def _get_esptool_args(args):
+    esptool_path = os.path.join(os.environ["IDF_PATH"], "components/esptool_py/esptool/esptool.py")
+    result = [ PYTHON, esptool_path ]
+    if args.port is not None:
+        result += [ "-p", args.port ]
+    result += [ "-b", str(args.baud) ]
+    return result
+
+def flash(action, args):
+    """
+    Run esptool to flash the entire project, from an argfile generated by the build system
+    """
+    flasher_args_path = {
+        "bootloader-flash":      "flash_bootloader_args",
+        "partition_table-flash": "flash_partition_table_args",
+        "app-flash":             "flash_app_args",
+        "flash":                 "flash_project_args",
+    }[action]
+    esptool_args = _get_esptool_args(args)
+    esptool_args += [ "write_flash", "@"+flasher_args_path ]
+    subprocess.check_call(esptool_args, cwd=args.build_dir)
+
+def erase_flash(action, args):
+    esptool_args = _get_esptool_args(args)
+    esptool_args += [ "erase_flash" ]
+    subprocess.check_call(esptool_args, cwd=args.build_dir)
+
+def monitor(action, args):
+    """
+    Run idf_monitor.py to watch build output
+    """
+    desc_path = os.path.join(args.build_dir, "project_description.json")
+    if not os.path.exists(desc_path):
+        _ensure_build_directory(args)
+    with open(desc_path, "r") as f:
+        project_desc = json.load(f)
+
+    elf_file = os.path.join(args.build_dir, project_desc["app_elf"])
+    if not os.path.exists(elf_file):
+        raise RuntimeError("ELF file '%s' not found. You need to build & flash the project before running 'monitor', and the binary on the device must match the one in the build directory exactly. Try 'idf.py flash monitor'." % elf_file)
+    idf_monitor = os.path.join(os.environ["IDF_PATH"], "tools/idf_monitor.py")
+    monitor_args = [PYTHON, idf_monitor ]
+    if args.port is not None:
+        monitor_args += [ "-p", args.port ]
+    monitor_args += [ "-b", project_desc["monitor_baud"] ]
+    monitor_args += [ elf_file ]
+    subprocess.check_call(monitor_args, cwd=args.build_dir)
+
+def clean(action, args):
+    if not os.path.isdir(args.build_dir):
+        print("Build directory '%s' not found. Nothing to clean." % args.build_dir)
+        return
+    build_target("clean", args)
+
+def fullclean(action, args):
+    build_dir = args.build_dir
+    if not os.path.isdir(build_dir):
+        print("Build directory '%s' not found. Nothing to clean." % build_dir)
+        return
+    if len(os.listdir(build_dir)) == 0:
+        print("Build directory '%s' is empty. Nothing to clean." % build_dir)
+        return
+
+    if not os.path.exists(os.path.join(build_dir, "CMakeCache.txt")):
+        raise RuntimeError("Directory '%s' doesn't seem to be a CMake build directory. Refusing to automatically delete files in this directory. Delete the directory manually to 'clean' it." % build_dir)
+    red_flags = [ "CMakeLists.txt", ".git", ".svn" ]
+    for red in red_flags:
+        red = os.path.join(build_dir, red)
+        if os.path.exists(red):
+            raise RuntimeError("Refusing to automatically delete files in directory containing '%s'. Delete files manually if you're sure." % red)
+    # OK, delete everything in the build directory...
+    for f in os.listdir(build_dir):  # TODO: once we are Python 3 only, this can be os.scandir()
+        f = os.path.join(build_dir, f)
+        if os.path.isdir(f):
+            shutil.rmtree(f)
+        else:
+            os.remove(f)
+
+ACTIONS = {
+    # action name : ( function (or alias), dependencies, order-only dependencies )
+    "all" :                  ( build_target, [], [ "menuconfig", "clean", "fullclean" ] ),
+    "build":                 ( "all",        [], [] ),  # build is same as 'all' target
+    "clean":                 ( clean,        [], [ "fullclean" ] ),
+    "fullclean":             ( fullclean,    [], [] ),
+    "menuconfig":            ( build_target, [], [] ),
+    "size":                  ( build_target, [], [ "app" ] ),
+    "size-components":       ( build_target, [], [ "app" ] ),
+    "size-files":            ( build_target, [], [ "app" ] ),
+    "bootloader":            ( build_target, [], [] ),
+    "bootloader-clean":      ( build_target, [], [] ),
+    "bootloader-flash":      ( flash,        [ "bootloader" ], [] ),
+    "app":                   ( build_target, [], [] ),
+    "app-flash":             ( flash,        [], [ "app" ]),
+    "partition_table":       ( build_target, [], [] ),
+    "partition_table-flash": ( flash,        [ "partition_table" ], []),
+    "flash":                 ( flash,        [ "all" ], [ ] ),
+    "erase_flash":           ( erase_flash,  [], []),
+    "monitor":               ( monitor,      [], [ "flash", "partition_table-flash", "bootloader-flash", "app-flash" ]),
+}
+
+
+def main():
+    parser = argparse.ArgumentParser(description='ESP-IDF build management tool')
+    parser.add_argument('-p', '--port', help="Serial port", default=None)
+    parser.add_argument('-b', '--baud', help="Baud rate", default=460800)
+    parser.add_argument('-C', '--project-dir', help="Project directory", default=os.getcwd())
+    parser.add_argument('-B', '--build-dir', help="Build directory", default=None)
+    parser.add_argument('-G', '--generator', help="Cmake generator", choices=GENERATOR_CMDS.keys())
+    parser.add_argument('actions', help="Actions (build targets or other operations)", nargs='+',
+                        choices=ACTIONS.keys())
+
+    args = parser.parse_args()
+
+    check_environment()
+
+    # Advanced parameter checks
+    if args.build_dir is not None and os.path.realpath(args.project_dir) == os.path.realpath(args.build_dir):
+        raise RuntimeError("Setting the build directory to the project directory is not supported. Suggest dropping --build-dir option, the default is a 'build' subdirectory inside the project directory.")
+    if args.build_dir is None:
+        args.build_dir = os.path.join(args.project_dir, "build")
+    args.build_dir = os.path.realpath(args.build_dir)
+
+    completed_actions = set()
+    def execute_action(action, remaining_actions):
+        ( function, dependencies, order_dependencies ) = ACTIONS[action]
+        # very simple dependency management, build a set of completed actions and make sure
+        # all dependencies are in it
+        for dep in dependencies:
+            if not dep in completed_actions:
+                execute_action(dep, remaining_actions)
+        for dep in order_dependencies:
+            if dep in remaining_actions and not dep in completed_actions:
+                execute_action(dep, remaining_actions)
+
+        if action in completed_actions:
+            pass  # we've already done this, don't do it twice...
+        elif function in ACTIONS:  # alias of another action
+            execute_action(function, remaining_actions)
+        else:
+            function(action, args)
+
+        completed_actions.add(action)
+
+    while len(args.actions) > 0:
+        execute_action(args.actions[0], args.actions[1:])
+        args.actions.pop(0)
+
+
+if __name__ == "__main__":
+    main()
+
diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
index 00c92c3b6..13c741505 100755
--- a/tools/kconfig_new/confgen.py
+++ b/tools/kconfig_new/confgen.py
@@ -25,6 +25,7 @@ import sys
 import os
 import os.path
 import tempfile
+import json
 
 import gen_kconfig_doc
 import kconfiglib
@@ -149,6 +150,26 @@ def write_cmake(config, filename):
                     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:
@@ -167,7 +188,9 @@ OUTPUT_FORMATS = {
     "config" : write_config,
     "header" : write_header,
     "cmake" : write_cmake,
-    "docs" : gen_kconfig_doc.write_docs }
+    "docs" : gen_kconfig_doc.write_docs,
+    "json" : write_json,
+    }
 
 class FatalError(RuntimeError):
     """

From e94db98e739d247793a9bdc7e69d6d54bd23adb0 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 9 Feb 2018 16:09:47 +0800
Subject: [PATCH 022/112] link bootloader to libgcc (shouldn't be necessary, is
 necessary...)

---
 components/bootloader/subproject/CMakeLists.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index f3cc23ac1..ae24d8cee 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -20,3 +20,5 @@ target_link_libraries(bootloader.elf "-L ${CMAKE_CURRENT_SOURCE_DIR}/main")
 target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
 target_link_libraries(bootloader.elf "-T esp32.bootloader.rom.ld")
 target_link_libraries(bootloader.elf "${BOOTLOADER_LINKER_ARGS}")
+target_link_libraries(bootloader.elf gcc)
+

From 04a944598f244b7a3cc743c790a20b9dd4ca5b7c Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 9 Feb 2018 16:35:35 +0800
Subject: [PATCH 023/112] cmake: Export compile_commands.json as part of build

---
 tools/cmake/idf_functions.cmake | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index c6ecd5ed5..458425f33 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -28,6 +28,8 @@ macro(idf_set_global_variables)
   # path to idf.py tool
   set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
 
+  # generate compile_commands.json
+  set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
 endmacro()
 
 # Add all the IDF global compiler & preprocessor options

From abef220b13e8837705e1a8bd30a2ad526f64ebd2 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 15 Feb 2018 14:38:58 +1100
Subject: [PATCH 024/112] cmake: Allow selecting toolchain file based on config

Refactor IDF "project" functionality under a wrapping of the default
"project" command, so we can tweak it a bit...

Will need more testing in other environments.
---
 components/bootloader/project_include.cmake   |   2 +-
 .../bootloader/subproject/CMakeLists.txt      |   5 +-
 .../get-started/hello_world/CMakeLists.txt    |   4 +-
 tools/cmake/idf_functions.cmake               |  17 +--
 tools/cmake/project.cmake                     | 118 +++++++++++-------
 .../cmake/toolchain-esp32.cmake               |   0
 6 files changed, 83 insertions(+), 63 deletions(-)
 rename toolchain.cmake => tools/cmake/toolchain-esp32.cmake (100%)

diff --git a/components/bootloader/project_include.cmake b/components/bootloader/project_include.cmake
index bfefcb8a2..cef56f47e 100644
--- a/components/bootloader/project_include.cmake
+++ b/components/bootloader/project_include.cmake
@@ -1,4 +1,4 @@
-if(IS_BOOTLOADER_BUILD)
+if(BOOTLOADER_BUILD)
   return()  # don't keep recursing!
 endif()
 
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index ae24d8cee..e5d2c18bf 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -1,20 +1,17 @@
 cmake_minimum_required(VERSION 3.5)
-set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
 
 if(NOT SDKCONFIG)
   message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the parent build process.")
 endif()
 
-project(bootloader ASM C CXX)
-
 set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash micro-ecc soc)
 set(BOOTLOADER_BUILD 1)
-set(IS_BOOTLOADER_BUILD 1)  # deprecated, use BOOTLOADER_BUILD
 add_definitions(-DBOOTLOADER_BUILD=1)
 
 set(MAIN_SRCS main/bootloader_start.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bootloader)
 
 target_link_libraries(bootloader.elf "-L ${CMAKE_CURRENT_SOURCE_DIR}/main")
 target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
index 4ae205fa2..e0b4ccdef 100644
--- a/examples/get-started/hello_world/CMakeLists.txt
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -1,10 +1,8 @@
 # The following five lines of boilerplate have to be in your project's CMakeLists
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
-set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
-
-project(hello-world ASM C CXX)
 
 set(MAIN_SRCS main/hello_world_main.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(hello-world)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 458425f33..9cab9bb56 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -2,6 +2,12 @@
 
 include(crosstool_version_check)
 
+#
+# Set some variables used by rest of the build
+#
+# Note at the time this macro is expanded, the config is not yet
+# loaded and the toolchain and project are not yet set
+#
 macro(idf_set_global_variables)
   # Note that CONFIG_xxx is not available when this function is called
 
@@ -22,9 +28,6 @@ macro(idf_set_global_variables)
   # Tell cmake to drop executables in the top-level build dir
   set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}")
 
-  # cmake cross-toolchain doesn't include any gcc binutils names
-  set(CMAKE_OBJCOPY xtensa-esp32-elf-objcopy)
-
   # path to idf.py tool
   set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
 
@@ -93,20 +96,18 @@ endfunction(idf_set_global_compiler_options)
 function(idf_verify_environment)
 
   if(NOT CMAKE_PROJECT_NAME)
-    message(FATAL_ERROR "Project top-level CMakeLists.txt file must call project() before including project.cmake")
+    message(FATAL_ERROR "Internal error, IDF project.cmake should have set this variable already")
   endif()
 
   # Check toolchain is configured properly in cmake
   if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
-    message(FATAL_ERROR "Project top-level CMakeLists.txt file needs to set CMAKE_TOOLCHAIN_FILE "
-      "before including project.cmake.\n"
-      "Update CMakeLists.txt to match the template project and delete CMakeCache.txt before "
-      "re-running cmake.")
+    message(FATAL_ERROR "Internal error, toolchain has not been set correctly by project")
   endif()
 
   #
   # Warn if the toolchain version doesn't match
   #
+  # TODO: make these platform-specific for diff toolchains
   gcc_version_check("5.2.0")
   crosstool_version_check("1.22.0-80-g6c4433a")
 
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index b23f39d73..7ed6b190d 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -24,55 +24,79 @@ include(idf_functions)
 
 set_default(PYTHON "python")
 
-# Verify the environment is configured correctly
-idf_verify_environment()
-
-# Set global variables used by rest of the build
-idf_set_global_variables()
-
-# Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
-components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
-
-kconfig_set_variables()
-
-kconfig_process_config()
-
-# Include sdkconfig.cmake so rest of the build knows the configuration
-include(${SDKCONFIG_CMAKE})
-
-# Add some idf-wide definitions
-idf_set_global_compiler_options()
-
-# Check git version (may trigger reruns of cmake)
-# & set GIT_REVISION/IDF_VER variable
-git_describe(GIT_REVISION)
-add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
-git_submodule_check("${IDF_PATH}")
-
-# Include any top-level project_include.cmake files from components
-foreach(component ${COMPONENT_PATHS})
-  include_if_exists("${component}/project_include.cmake")
-endforeach()
-
+# project
 #
-# Add each component to the build as a library
+# This macro wraps the cmake 'project' command to add
+# all of the IDF-specific functionality required
 #
-foreach(component ${COMPONENT_PATHS})
-  get_filename_component(component_name ${component} NAME)
-  add_subdirectory(${component} ${component_name})
-endforeach()
+# Implementation Note: This macro wraps 'project' on purpose, because cmake has some
+# backwards-compatible magic where if you don't call "project" in the top-level
+# CMakeLists file, it will call it implicitly. However, the implict project will not
+# have CMAKE_TOOLCHAIN_FILE set and therefore tries to create a native build project.
+#
+# Therefore, to keep all the IDF "build magic", the cleanest way is to keep the
+# top-level "project" call but customize it to do what we want in the IDF build...
+#
+macro(project name)
+  # Set global variables used by rest of the build
+  idf_set_global_variables()
 
-#
-# Add the app executable to the build (has name of PROJECT.elf)
-#
-idf_add_executable()
+  # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
+  components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
 
-# Write project description JSON file
-configure_file("${CMAKE_CURRENT_LIST_DIR}/project_description.json.in"
-  "${CMAKE_BINARY_DIR}/project_description.json")
+  kconfig_set_variables()
 
-#
-# Finish component registration (add cross-dependencies, make
-# executable dependent on all components)
-#
-components_finish_registration()
+  kconfig_process_config()
+
+  # Include sdkconfig.cmake so rest of the build knows the configuration
+  include(${SDKCONFIG_CMAKE})
+
+  # Now the configuration is loaded, set the toolchain appropriately
+  #
+  # TODO: support more toolchains than just ESP32
+  set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/tools/cmake/toolchain-esp32.cmake)
+
+  # Declare the actual cmake-level project
+  _project(${name} ASM C CXX)
+
+  # Verify the environment is configured correctly
+  idf_verify_environment()
+
+  # Add some idf-wide definitions
+  idf_set_global_compiler_options()
+
+  # Check git version (may trigger reruns of cmake)
+  # & set GIT_REVISION/IDF_VER variable
+  git_describe(GIT_REVISION)
+  add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
+  git_submodule_check("${IDF_PATH}")
+
+  # Include any top-level project_include.cmake files from components
+  foreach(component ${COMPONENT_PATHS})
+    include_if_exists("${component}/project_include.cmake")
+  endforeach()
+
+  #
+  # Add each component to the build as a library
+  #
+  foreach(component ${COMPONENT_PATHS})
+    get_filename_component(component_name ${component} NAME)
+    add_subdirectory(${component} ${component_name})
+  endforeach()
+
+  #
+  # Add the app executable to the build (has name of PROJECT.elf)
+  #
+  idf_add_executable()
+
+  # Write project description JSON file
+  configure_file("${IDF_PATH}/tools/cmake/project_description.json.in"
+    "${CMAKE_BINARY_DIR}/project_description.json")
+
+  #
+  # Finish component registration (add cross-dependencies, make
+  # executable dependent on all components)
+  #
+  components_finish_registration()
+
+endmacro(project)
diff --git a/toolchain.cmake b/tools/cmake/toolchain-esp32.cmake
similarity index 100%
rename from toolchain.cmake
rename to tools/cmake/toolchain-esp32.cmake

From 4d7bc8e8ba0ea0ccce62c553ed2d3228a2ea36e0 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 16 Feb 2018 15:32:08 +1100
Subject: [PATCH 025/112] idf.py: Improve status output, error message output

---
 tools/idf.py | 74 ++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 52 insertions(+), 22 deletions(-)

diff --git a/tools/idf.py b/tools/idf.py
index 4b3ebc371..9580baa3d 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -31,6 +31,12 @@ import re
 import shutil
 import json
 
+class FatalError(RuntimeError):
+    """
+    Wrapper class for runtime errors that aren't caused by bugs in idf.py or the build proces.s
+    """
+    pass
+
 # Use this Python interpreter for any subprocesses we launch
 PYTHON=sys.executable
 
@@ -56,6 +62,22 @@ GENERATORS = [
     ]
 GENERATOR_CMDS = dict( (a[0], a[1]) for a in GENERATORS )
 
+def _run_tool(tool_name, args, cwd):
+    def quote_arg(arg):
+        " Quote 'arg' if necessary "
+        if " " in arg and not (arg.startswith('"') or arg.startswith("'")):
+            return "'" + arg + "'"
+        return arg
+    display_args = " ".join(quote_arg(arg) for arg in args)
+    print("Running %s in directory %s" % (tool_name, quote_arg(cwd)))
+    print('Executing "%s"...' % display_args)
+    try:
+        # Note: we explicitly pass in os.environ here, as we may have set IDF_PATH there during startup
+        subprocess.check_call(args, env=os.environ, cwd=cwd)
+    except subprocess.CalledProcessError as e:
+        raise FatalError("%s failed with exit code %d" % (tool_name, e.returncode))
+
+
 def check_environment():
     """
     Verify the environment contains the top-level tools we need to operate
@@ -63,7 +85,7 @@ def check_environment():
     (cmake will check a lot of other things)
     """
     if not executable_exists(["cmake", "--version"]):
-        raise RuntimeError("'cmake' must be available on the PATH to use idf.py")
+        raise FatalError("'cmake' must be available on the PATH to use idf.py")
     # find the directory idf.py is in, then the parent directory of this, and assume this is IDF_PATH
     detected_idf_path = os.path.realpath(os.path.join(os.path.dirname(__file__), ".."))
     if "IDF_PATH" in os.environ:
@@ -88,7 +110,7 @@ def detect_cmake_generator():
     for (generator, _, version_check) in GENERATORS:
         if executable_exists(version_check):
             return generator
-    raise RuntimeError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")
+    raise FatalError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")
 
 def _ensure_build_directory(args):
     """Check the build directory exists and that cmake has been run there.
@@ -104,11 +126,11 @@ def _ensure_build_directory(args):
     # Verify the project directory
     if not os.path.isdir(project_dir):
         if not os.path.exists(project_dir):
-            raise RuntimeError("Project directory %s does not exist")
+            raise FatalError("Project directory %s does not exist")
         else:
-            raise RuntimeError("%s must be a project directory")
+            raise FatalError("%s must be a project directory")
     if not os.path.exists(os.path.join(project_dir, "CMakeLists.txt")):
-        raise RuntimeError("CMakeLists.txt not found in project directory %s" % project_dir)
+        raise FatalError("CMakeLists.txt not found in project directory %s" % project_dir)
 
     # Verify/create the build directory
     build_dir = args.build_dir
@@ -118,12 +140,12 @@ def _ensure_build_directory(args):
     if not os.path.exists(cache_path):
         if args.generator is None:
             args.generator = detect_cmake_generator()
-        print("Running cmake...")
-        # Note: we explicitly pass in os.environ here, as we may have set IDF_PATH there during startup
         try:
-            subprocess.check_call(["cmake", "-G", args.generator, project_dir], env=os.environ, cwd=args.build_dir)
+            _run_tool("cmake", ["cmake", "-G", args.generator, project_dir], cwd=args.build_dir)
         except:
-            if os.path.exists(cache_path):  # don't allow partial CMakeCache.txt files, to keep the "should I run cmake?" logic simple
+            # don't allow partially valid CMakeCache.txt files,
+            # to keep the "should I run cmake?" logic simple
+            if os.path.exists(cache_path):
                 os.remove(cache_path)
             raise
 
@@ -136,13 +158,13 @@ def _ensure_build_directory(args):
     if args.generator is None:
         args.generator = generator  # reuse the previously configured generator, if none was given
     if generator != args.generator:
-        raise RuntimeError("Build is configured for generator '%s' not '%s'. Run 'idf.py fullclean' to start again."
+        raise FatalError("Build is configured for generator '%s' not '%s'. Run 'idf.py fullclean' to start again."
                            % (generator, args.generator))
 
     try:
         home_dir = cache["CMAKE_HOME_DIRECTORY"]
         if os.path.realpath(home_dir) != os.path.realpath(project_dir):
-            raise RuntimeError("Build directory '%s' configured for project '%s' not '%s'. Run 'idf.py fullclean' to start again."
+            raise FatalError("Build directory '%s' configured for project '%s' not '%s'. Run 'idf.py fullclean' to start again."
                             % (build_dir, os.path.realpath(home_dir), os.path.realpath(project_dir)))
     except KeyError:
         pass  # if cmake failed part way, CMAKE_HOME_DIRECTORY may not be set yet
@@ -175,8 +197,8 @@ def build_target(target_name, args):
     """
     _ensure_build_directory(args)
     generator_cmd = GENERATOR_CMDS[args.generator]
-    print("Running '%s %s' in %s..." % (generator_cmd, target_name, args.build_dir))
-    subprocess.check_call(generator_cmd + [target_name], cwd=args.build_dir)
+    _run_tool(generator_cmd[0], generator_cmd + [target_name], args.build_dir)
+
 
 def _get_esptool_args(args):
     esptool_path = os.path.join(os.environ["IDF_PATH"], "components/esptool_py/esptool/esptool.py")
@@ -190,7 +212,7 @@ def flash(action, args):
     """
     Run esptool to flash the entire project, from an argfile generated by the build system
     """
-    flasher_args_path = {
+    flasher_args_path = {  # action -> name of flasher args file generated by build system
         "bootloader-flash":      "flash_bootloader_args",
         "partition_table-flash": "flash_partition_table_args",
         "app-flash":             "flash_app_args",
@@ -198,12 +220,14 @@ def flash(action, args):
     }[action]
     esptool_args = _get_esptool_args(args)
     esptool_args += [ "write_flash", "@"+flasher_args_path ]
-    subprocess.check_call(esptool_args, cwd=args.build_dir)
+    _run_tool("esptool.py", esptool_args, args.build_dir)
+
 
 def erase_flash(action, args):
     esptool_args = _get_esptool_args(args)
     esptool_args += [ "erase_flash" ]
-    subprocess.check_call(esptool_args, cwd=args.build_dir)
+    _run_tool("esptool.py", esptool_args, args.build_dir)
+
 
 def monitor(action, args):
     """
@@ -217,14 +241,15 @@ def monitor(action, args):
 
     elf_file = os.path.join(args.build_dir, project_desc["app_elf"])
     if not os.path.exists(elf_file):
-        raise RuntimeError("ELF file '%s' not found. You need to build & flash the project before running 'monitor', and the binary on the device must match the one in the build directory exactly. Try 'idf.py flash monitor'." % elf_file)
+        raise FatalError("ELF file '%s' not found. You need to build & flash the project before running 'monitor', and the binary on the device must match the one in the build directory exactly. Try 'idf.py flash monitor'." % elf_file)
     idf_monitor = os.path.join(os.environ["IDF_PATH"], "tools/idf_monitor.py")
     monitor_args = [PYTHON, idf_monitor ]
     if args.port is not None:
         monitor_args += [ "-p", args.port ]
     monitor_args += [ "-b", project_desc["monitor_baud"] ]
     monitor_args += [ elf_file ]
-    subprocess.check_call(monitor_args, cwd=args.build_dir)
+    _run_tool("idf_monitor", monitor_args, args.build_dir)
+
 
 def clean(action, args):
     if not os.path.isdir(args.build_dir):
@@ -242,12 +267,12 @@ def fullclean(action, args):
         return
 
     if not os.path.exists(os.path.join(build_dir, "CMakeCache.txt")):
-        raise RuntimeError("Directory '%s' doesn't seem to be a CMake build directory. Refusing to automatically delete files in this directory. Delete the directory manually to 'clean' it." % build_dir)
+        raise FatalError("Directory '%s' doesn't seem to be a CMake build directory. Refusing to automatically delete files in this directory. Delete the directory manually to 'clean' it." % build_dir)
     red_flags = [ "CMakeLists.txt", ".git", ".svn" ]
     for red in red_flags:
         red = os.path.join(build_dir, red)
         if os.path.exists(red):
-            raise RuntimeError("Refusing to automatically delete files in directory containing '%s'. Delete files manually if you're sure." % red)
+            raise FatalError("Refusing to automatically delete files in directory containing '%s'. Delete files manually if you're sure." % red)
     # OK, delete everything in the build directory...
     for f in os.listdir(build_dir):  # TODO: once we are Python 3 only, this can be os.scandir()
         f = os.path.join(build_dir, f)
@@ -295,7 +320,7 @@ def main():
 
     # Advanced parameter checks
     if args.build_dir is not None and os.path.realpath(args.project_dir) == os.path.realpath(args.build_dir):
-        raise RuntimeError("Setting the build directory to the project directory is not supported. Suggest dropping --build-dir option, the default is a 'build' subdirectory inside the project directory.")
+        raise FatalError("Setting the build directory to the project directory is not supported. Suggest dropping --build-dir option, the default is a 'build' subdirectory inside the project directory.")
     if args.build_dir is None:
         args.build_dir = os.path.join(args.project_dir, "build")
     args.build_dir = os.path.realpath(args.build_dir)
@@ -327,5 +352,10 @@ def main():
 
 
 if __name__ == "__main__":
-    main()
+    try:
+        main()
+    except FatalError as e:
+        print(e)
+        sys.exit(2)
+
 

From 7d9ba66f838e67d94d0d01f95a98053cc11b2bbf Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 13:21:51 +1100
Subject: [PATCH 026/112] idf.py: Add reconfigure command

---
 tools/idf.py | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/tools/idf.py b/tools/idf.py
index 9580baa3d..fe118639c 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -112,7 +112,7 @@ def detect_cmake_generator():
             return generator
     raise FatalError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")
 
-def _ensure_build_directory(args):
+def _ensure_build_directory(args, always_run_cmake=False):
     """Check the build directory exists and that cmake has been run there.
 
     If this isn't the case, create the build directory (if necessary) and
@@ -137,7 +137,7 @@ def _ensure_build_directory(args):
     if not os.path.isdir(build_dir):
         os.mkdir(build_dir)
     cache_path = os.path.join(build_dir, "CMakeCache.txt")
-    if not os.path.exists(cache_path):
+    if not os.path.exists(cache_path) or always_run_cmake:
         if args.generator is None:
             args.generator = detect_cmake_generator()
         try:
@@ -257,6 +257,9 @@ def clean(action, args):
         return
     build_target("clean", args)
 
+def reconfigure(action, args):
+    _ensure_build_directory(args, True)
+
 def fullclean(action, args):
     build_dir = args.build_dir
     if not os.path.isdir(build_dir):
@@ -283,10 +286,11 @@ def fullclean(action, args):
 
 ACTIONS = {
     # action name : ( function (or alias), dependencies, order-only dependencies )
-    "all" :                  ( build_target, [], [ "menuconfig", "clean", "fullclean" ] ),
+    "all" :                  ( build_target, [], [ "reconfigure", "menuconfig", "clean", "fullclean" ] ),
     "build":                 ( "all",        [], [] ),  # build is same as 'all' target
     "clean":                 ( clean,        [], [ "fullclean" ] ),
     "fullclean":             ( fullclean,    [], [] ),
+    "reconfigure":           ( reconfigure,  [], [] ),
     "menuconfig":            ( build_target, [], [] ),
     "size":                  ( build_target, [], [ "app" ] ),
     "size-components":       ( build_target, [], [ "app" ] ),
@@ -294,9 +298,9 @@ ACTIONS = {
     "bootloader":            ( build_target, [], [] ),
     "bootloader-clean":      ( build_target, [], [] ),
     "bootloader-flash":      ( flash,        [ "bootloader" ], [] ),
-    "app":                   ( build_target, [], [] ),
+    "app":                   ( build_target, [], [ "clean", "fullclean", "reconfigure" ] ),
     "app-flash":             ( flash,        [], [ "app" ]),
-    "partition_table":       ( build_target, [], [] ),
+    "partition_table":       ( build_target, [], [ "reconfigure" ] ),
     "partition_table-flash": ( flash,        [ "partition_table" ], []),
     "flash":                 ( flash,        [ "all" ], [ ] ),
     "erase_flash":           ( erase_flash,  [], []),

From 95e17d6d926bbd99f9e7ef367084de5633df4247 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 13:21:37 +1100
Subject: [PATCH 027/112] cmake: Allow GetGitRevisionDescription to take
 arbitrary directory paths

---
 .../GetGitRevisionDescription.cmake           | 21 +++++++++++--------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/tools/cmake/third_party/GetGitRevisionDescription.cmake b/tools/cmake/third_party/GetGitRevisionDescription.cmake
index 85eae1562..6c711bbd4 100644
--- a/tools/cmake/third_party/GetGitRevisionDescription.cmake
+++ b/tools/cmake/third_party/GetGitRevisionDescription.cmake
@@ -3,16 +3,16 @@
 # These functions force a re-configure on each git commit so that you can
 # trust the values of the variables in your build system.
 #
-#  get_git_head_revision(<refspecvar> <hashvar> [<additional arguments to git describe> ...])
+#  get_git_head_revision(<refspecvar> <hashvar> <repo dir> [<additional arguments to git describe> ...])
 #
 # Returns the refspec and sha hash of the current head revision
 #
-#  git_describe(<var> [<additional arguments to git describe> ...])
+#  git_describe(<var> <repo dir> [<additional arguments to git describe> ...])
 #
 # Returns the results of git describe on the source tree, and adjusting
 # the output so that it tests false if an error occurs.
 #
-#  git_get_exact_tag(<var> [<additional arguments to git describe> ...])
+#  git_get_exact_tag(<var> <repo dir> [<additional arguments to git describe> ...])
 #
 # Returns the results of git describe --exact-match on the source tree,
 # and adjusting the output so that it tests false if there was no exact
@@ -29,6 +29,9 @@
 # Distributed under the Boost Software License, Version 1.0.
 # (See accompanying file LICENSE_1_0.txt or copy at
 # http://www.boost.org/LICENSE_1_0.txt)
+#
+# Updated 2018 Espressif Systems to add _repo_dir argument
+# to get revision of other repositories
 
 if(__get_git_revision_description)
 	return()
@@ -39,8 +42,8 @@ set(__get_git_revision_description YES)
 # to find the path to this module rather than the path to a calling list file
 get_filename_component(_gitdescmoddir ${CMAKE_CURRENT_LIST_FILE} PATH)
 
-function(get_git_head_revision _refspecvar _hashvar)
-	set(GIT_PARENT_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
+function(get_git_head_revision _refspecvar _hashvar _repo_dir)
+    set(GIT_PARENT_DIR "${_repo_dir}")
 	set(GIT_DIR "${GIT_PARENT_DIR}/.git")
 	while(NOT EXISTS "${GIT_DIR}")	# .git dir not found, search parent directories
 		set(GIT_PREVIOUS_PARENT "${GIT_PARENT_DIR}")
@@ -80,11 +83,11 @@ function(get_git_head_revision _refspecvar _hashvar)
 	set(${_hashvar} "${HEAD_HASH}" PARENT_SCOPE)
 endfunction()
 
-function(git_describe _var)
+function(git_describe _var _repo_dir)
 	if(NOT GIT_FOUND)
 		find_package(Git QUIET)
 	endif()
-	get_git_head_revision(refspec hash)
+	get_git_head_revision(refspec hash "${_repo_dir}")
 	if(NOT GIT_FOUND)
 		set(${_var} "GIT-NOTFOUND" PARENT_SCOPE)
 		return()
@@ -124,7 +127,7 @@ function(git_describe _var)
 	set(${_var} "${out}" PARENT_SCOPE)
 endfunction()
 
-function(git_get_exact_tag _var)
-	git_describe(out --exact-match ${ARGN})
+function(git_get_exact_tag _var _repo_dir)
+	git_describe(out "${_repo_dir}" --exact-match ${ARGN})
 	set(${_var} "${out}" PARENT_SCOPE)
 endfunction()

From 9f8cdd3572beff7fb9b0d55630bff40b59b0086c Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 22 Feb 2018 15:05:05 +1100
Subject: [PATCH 028/112] cmake: Add "Preview release" getting start guide &
 build system documentation

---
 components/expat/CMakeLists.txt               |   2 +-
 components/libsodium/CMakeLists.txt           |   6 +-
 components/lwip/CMakeLists.txt                |   4 +-
 components/wpa_supplicant/CMakeLists.txt      |   4 +-
 docs/en/api-guides/build-system-cmake.rst     | 749 ++++++++++++++++++
 docs/en/api-guides/cmake-preview-index.rst    |  10 +
 docs/en/contribute/style-guide.rst            |   2 +
 .../add-idf_path-to-profile-cmake.rst         |  66 ++
 .../establish-serial-connection.rst           |   2 +
 docs/en/get-started/index-cmake.rst           | 346 ++++++++
 docs/en/get-started/linux-setup-cmake.rst     | 113 +++
 docs/en/get-started/macos-setup-cmake.rst     |  61 ++
 docs/en/get-started/windows-setup-cmake.rst   |  78 ++
 docs/en/index.rst                             |   1 +
 tools/cmake/components.cmake                  |  31 +-
 tools/cmake/idf_functions.cmake               |  32 +-
 tools/cmake/kconfig.cmake                     |   6 +-
 tools/cmake/project.cmake                     |  29 +-
 tools/cmake/project_description.json.in       |   2 +-
 tools/idf.py                                  |   7 +-
 20 files changed, 1510 insertions(+), 41 deletions(-)
 create mode 100644 docs/en/api-guides/build-system-cmake.rst
 create mode 100644 docs/en/api-guides/cmake-preview-index.rst
 create mode 100644 docs/en/get-started/add-idf_path-to-profile-cmake.rst
 create mode 100644 docs/en/get-started/index-cmake.rst
 create mode 100644 docs/en/get-started/linux-setup-cmake.rst
 create mode 100644 docs/en/get-started/macos-setup-cmake.rst
 create mode 100644 docs/en/get-started/windows-setup-cmake.rst

diff --git a/components/expat/CMakeLists.txt b/components/expat/CMakeLists.txt
index c35d79ce6..169dd4f89 100644
--- a/components/expat/CMakeLists.txt
+++ b/components/expat/CMakeLists.txt
@@ -3,7 +3,7 @@ set(COMPONENT_SRCDIRS library port)
 
 register_component()
 
-target_compile_definitions(expat PRIVATE HAVE_EXPAT_CONFIG_H)
+component_compile_definitions(HAVE_EXPAT_CONFIG_H)
 
 # patch around warnings in third-party files
 set_source_files_properties(
diff --git a/components/libsodium/CMakeLists.txt b/components/libsodium/CMakeLists.txt
index f45025084..f35f19c22 100644
--- a/components/libsodium/CMakeLists.txt
+++ b/components/libsodium/CMakeLists.txt
@@ -72,7 +72,7 @@ set(COMPONENT_PRIV_INCLUDEDIRS ${SRC}/include/sodium port_include/sodium port)
 
 register_component()
 
-target_compile_definitions(libsodium PRIVATE
+component_compile_definitions(
 	CONFIGURED
 	NATIVE_LITTLE_ENDIAN
 	HAVE_WEAK_SYMBOLS
@@ -80,9 +80,7 @@ target_compile_definitions(libsodium PRIVATE
 	__STDC_CONSTANT_MACROS
 )
 
-target_compile_options(libsodium PRIVATE
-	-Wno-unknown-pragmas
-    )
+component_compile_options(-Wno-unknown-pragmas)
 
 # patch around warnings in third-party files
 set_source_files_properties(
diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
index 1ffa69f47..64dffb41d 100644
--- a/components/lwip/CMakeLists.txt
+++ b/components/lwip/CMakeLists.txt
@@ -18,9 +18,7 @@ set(COMPONENT_SRCDIRS
 
 register_component()
 
-target_compile_options(lwip PRIVATE
-	-Wno-address
-)
+component_compile_options(-Wno-address)
 
 # patch around warnings in third-party files
 set_source_files_properties(api/tcpip.c
diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
index 0b06eeeb4..1d2091656 100644
--- a/components/wpa_supplicant/CMakeLists.txt
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -3,5 +3,5 @@ set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 
 register_component()
 
-target_compile_definitions(wpa_supplicant PRIVATE __ets__)
-target_compile_options(wpa_supplicant PRIVATE -Wno-strict-aliasing)
+component_compile_definitions(__ets__)
+component_compile_options(-Wno-strict-aliasing)
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
new file mode 100644
index 000000000..607fb2e3f
--- /dev/null
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -0,0 +1,749 @@
+CMake-based Build System
+************************
+
+This document explains the CMake-based ESP-IDF build system and the concept of "components".
+
+Read this document if you want to know how to organise and build a new ESP-IDF project using the CMake-based build system.
+
+We recommend using the esp-idf-template_ project as a starting point for your project.
+
+Preview Release
+===============
+
+.. note::
+    The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The document describing the :doc:`fully supported non-CMake build system is here </api-guides/build-system>`.
+
+CMake-based build system preview release temporarily has the following limitations:
+
+- No instructions published for use with any IDEs.
+- No support for building ULP firmware as part of the build.
+- No support for flash encryption, secure boot.
+- ``idf.py monitor`` only runs at 115200bps
+- The rebuild/reflash commands inside monitor don't work correctly.
+
+These missing features will be added before CMake support is officially supported.
+
+Overview
+========
+
+An ESP-IDF project can be seen as an amalgamation of a number of components.
+For example, for a webserver that shows the current humidity, there could be:
+
+- The ESP32 base libraries (libc, ROM bindings, etc)
+- The WiFi drivers
+- A TCP/IP stack
+- The FreeRTOS operating system
+- A webserver
+- A driver for the humidity sensor
+- Main code tying it all together
+
+ESP-IDF makes these components explicit and configurable. To do that,
+when a project is compiled, the build system will look up all the
+components in the ESP-IDF directories, the project directories and
+(optionally) in additional custom component directories. It then
+allows the user to configure the ESP-IDF project using a a text-based
+menu system to customize each component. After the components in the
+project are configured, the build system will compile the project.
+
+Concepts
+--------
+
+- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader.
+
+- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
+
+- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
+
+- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
+
+Some things are not part of the project:
+
+- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
+
+- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
+
+Using the Build System
+======================
+
+idf.py
+------
+
+The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
+
+- CMake_, which configures the project to be built
+- A command line build tool (either Ninja_ build or `GNU Make`)
+- `esptool.py`_ for flashing ESP32.
+
+The :ref:`getting started guide <get-started-configure-cmake>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
+
+``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
+
+Type ``idf.py --help`` for a full list of commands. Here are a summary of a few:
+
+- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
+- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
+  - Create the build directory if needed. The subdirectory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
+  - Run CMake_ as necessary to configure the project and generate build files for the main build tool.
+  - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
+  Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
+- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
+- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care.
+- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
+- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
+- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor.
+
+Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean build flash monitor`` will perform a clean build of the project, then flash to the ESP32 and run the serial monitor.
+
+Advanced Commands
+^^^^^^^^^^^^^^^^^
+
+- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
+- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
+- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
+- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
+
+Using CMake Directly
+--------------------
+
+``idf.py`` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
+
+When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands::
+
+  mkdir -p build
+  cd build
+  cmake .. -G Ninja   # or 'GNU Make'
+  ninja
+
+In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: runnning ``ninja`` actually builds the project.
+
+It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguring.
+
+If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - for example running ``make menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
+
+.. note::
+   If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
+
+Using CMake in an IDE
+---------------------
+
+You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
+
+When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
+
+Example Project
+===============
+
+An example project directory tree might look like this::
+
+    - myProject/
+                 - CMakeLists.txt
+                 - sdkconfig
+                 - components/ - component1/ - CMakeLists.txt
+                                             - Kconfig
+                                             - src1.c
+                               - component2/ - CMakeLists.txt
+                                             - Kconfig
+                                             - src1.c
+                                             - include/ - component2.h
+                 - main/       - src1.c
+                               - src2.c
+
+                 - build/
+
+This example "myProject" contains the following elements:
+
+- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
+  implements the rest of the build system. Finally, it sets the project name and defines the project.
+
+- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
+
+- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
+
+- "main" directory is a special "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
+
+- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
+
+Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
+to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
+
+Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
+
+Project CMakeLists File
+=======================
+
+Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
+
+Minimal Example CMakeLists
+--------------------------
+
+::
+      cmake_minimum_required(VERSION 3.5)
+
+      set(MAIN_SRCS main/src1.c main/src2.c)
+
+      include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+      project(myProject)
+
+
+Mandatory Parts
+---------------
+
+The inclusion of these four lines, in the order shown above, is necessary for every project:
+
+- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
+- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged.
+
+  It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
+
+   ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
+- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
+- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
+
+
+Optional Project Variables
+--------------------------
+
+These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
+
+- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
+- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
+- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times.
+
+Any paths in these variables can be absolute paths, or set relative to the project directory.
+
+To set these variables, use the `cmake set command <cmake-set>` ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
+
+
+Component CMakeLists Files
+==========================
+
+Each project contains one or more components. Components can be part of esp-idf, part of the project's own components directory, or added from custom component directories (see above).
+
+A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
+
+Searching for Components
+------------------------
+
+The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose subdirectories are components.
+
+When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
+
+Multiple components with the same name
+--------------------------------------
+
+When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
+contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components
+with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
+If used in this way, the ESP-IDF directory itself can remain untouched.
+
+Minimal Component CMakeLists
+----------------------------
+
+The minimal component ``CMakeLists.txt`` file is as follows::
+
+  set(COMPONENT_SRCDIRS ".")
+  set(COMPONENT_ADD_INCLUDEDIRS "include")
+  register_component()
+
+- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
+- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for all other components, and the main source files.
+- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if() statement<cmake-if>` or similar), this component will not be built at all.
+
+Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
+
+See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
+
+.. _component variables:
+
+Preset Component Variables
+--------------------------
+
+The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
+
+- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
+- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
+
+The following variables are set at the project level, but available for use in component CMakeLists:
+
+- ``PROJECT_NAME``: Name of the project, as set in project Makefile
+- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
+- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
+- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. `More information here </api-reference/kconfig>`.
+- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
+
+If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
+
+Optional Project-Wide Component Variables
+-----------------------------------------
+
+The following variables can be set inside component ``CMakeLists.txt`` to control build settings across the entire project:
+
+- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
+  directory, which will be added to the include search path for
+  all components in the project. If an include directory is only needed to compile
+  this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
+- ``COMPONENT_DEPENDS``: Optional list of component names that should be
+  compiled before this component. This is not necessary for
+  link-time dependencies, because all component include directories
+  are available at all times. It is necessary if one component
+  generates an include file which you then want to include in another
+  component. Most components do not need to set this variable.
+
+
+Optional Component-Specific Variables
+-------------------------------------
+
+The following variables can be set inside ``component.mk`` to control the build of that component:
+
+- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
+  the component directory, which will be added to the include search
+  path for this component's source files only.
+- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
+  component directory, which will be searched for source files (``*.cpp``,
+  ``*.c``, ``*.S``). Set this to specify a list of directories
+  which contain source files.
+- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
+  If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add paths to include search paths.
+
+Controlling Component Compilation
+---------------------------------
+
+To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
+
+  component_compile_options(-Wno-unused-variable)
+
+This is a wrapper around the CMake `target_compile_options`_ command.
+
+To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
+
+    set_source_files_properties(mysrc.c
+        PROPERTIES COMPILE_FLAGS
+        -Wno-unused-variable
+    )
+
+This can be useful if there is upstream code that emits warnings.
+
+When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
+
+Component Configuration
+=======================
+
+Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
+configuration settings to add to the "make menuconfig" for this component.
+
+These settings are found under the "Component Settings" menu when menuconfig is run.
+
+To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with esp-idf.
+
+For an example, see `Adding conditional configuration`_.
+
+Preprocessor Definitions
+========================
+
+The ESP-IDF build system adds the following C preprocessor definitions on the command line:
+
+- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
+- ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
+
+Build Process Internals
+=======================
+
+For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`.
+
+project.cmake contents
+----------------------
+
+When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environmenmt.
+
+It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality.
+
+project function
+----------------
+
+The custom ``project()`` function performs the following steps:
+
+- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
+- Loads the project configuration from the ``sdkconfig`` file and produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
+- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
+- Declare the actual cmake-level project by calling the `CMake project function <project-function-cmake>`.
+- Load the git version. This includes some magic which will automatically re-run cmake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
+- Include ``project_include.cmake`` files from any components which have them.
+- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library <add-library-cmake>` function to add a library and then adds source files, compile options, etc.
+- Add the final app executable to the build.
+- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
+
+Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
+
+Debugging CMake
+---------------
+
+Some tips for debugging the esp-idf CMake-based build system:
+
+- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
+- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
+
+.. _warn-undefined-variables-cmake:
+
+Warning On Undefined Variables
+------------------------------
+
+By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
+
+If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
+
+Overriding Parts of the Project
+-------------------------------
+
+project_include.cmake
+^^^^^^^^^^^^^^^^^^^^^
+
+For components that have build requirements that must be evaluated before any component CMakeLists
+files are evaluated, you can create a file called ``project_include.cmake`` in the
+component directory. This makefile is included when ``project.cmake`` is evaluating the entire project.
+
+``project_include.cmake`` files are used heavily inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
+
+Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
+
+Take great care when setting variables or targets in this file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
+
+KConfig.projbuild
+^^^^^^^^^^^^^^^^^
+
+This is an equivalent to ``project_include.cmake`` for `component configuration` KConfig files. If you want to include
+configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
+
+Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
+
+
+Configuration-Only Components
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
+
+If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
+
+Example Component CMakeLists
+============================
+
+Because the build environment tries to set reasonable defaults that will work most
+of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
+
+Here are some more advanced examples of component CMakeLists files.
+
+
+Adding conditional configuration
+--------------------------------
+
+The configuration system can be used to conditionally compile some files
+depending on the options selected in the project configuration.
+
+
+``Kconfig``::
+
+    config FOO_ENABLE_BAR
+        bool "Enable the BAR feature."
+        help
+            This enables the BAR feature of the FOO component.
+
+``CMakeLists.txt``::
+
+    set(COMPONENT_SRCS "foo.c" "more_foo.c")
+
+    if(CONFIG_FOO_ENABLE_BAR)
+        list(APPEND COMPONENT_SRCS "bar.c")
+    endif(CONFIG_FOO_ENABLE_BAR)
+
+This example makes use of the CMake `if function <if-cmake>` and `list APPEND <list-cmake>` function.
+
+This can also be used to select or stub out an implementation, as such:
+
+``Kconfig``::
+
+    config ENABLE_LCD_OUTPUT
+        bool "Enable LCD output."
+        help
+            Select this if your board has a LCD.
+
+    config ENABLE_LCD_CONSOLE
+        bool "Output console text to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output debugging output to the lcd
+
+    config ENABLE_LCD_PLOT
+        bool "Output temperature plots to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output temperature plots
+
+
+``CMakeLists.txt``::
+
+    if(CONFIG_ENABLE_LCD_OUTPUT)
+       set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
+    else()
+       set(COMPONENT_SRCS lcd-dummy.c)
+    endif()
+
+    # We need font if either console or plot is enabled
+    if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_NEABLE_LCD_PLOT)
+      list(APPEND COMPONENT_SRCS "font.c")
+    endif()
+
+
+Source Code Generation
+----------------------
+
+Some components will have a situation where a source file isn't
+supplied with the component itself but has to be generated from
+another file. Say our component has a header file that consists of the
+converted binary data of a BMP file, converted using a hypothetical
+tool called bmp2h. The header file is then included in as C source
+file called graphics_lib.c::
+
+    COMPONENT_EXTRA_CLEAN := logo.h
+
+    add_custom_command(OUTPUT logo.h
+         COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
+         DEPENDS ${COMPONENT_PATH}/logo.bmp
+         VERBATIM)
+
+    add_custom_target(logo DEPENDS logo.h)
+    add_dependencies(${COMPONENT_NAME} logo)
+
+    set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
+         ADDITIONAL_MAKE_CLEAN_FILES logo.h)
+
+This answer is adapted from the `CMake FAQ entry <cmake-faq-generated-files>`, which contains some other examples that will also work with ESP-IDF builds.
+
+In this example, logo.h will be generated in the
+current directory (the build directory) while logo.bmp comes with the
+component and resides under the component path. Because logo.h is a
+generated file, it should be cleaned when make clean is called which
+why it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
+
+(Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
+
+If a a source file from another component included ``logo.h``, then this
+component's name would have to be added to the other component's
+``COMPONENT_DEPENDS`` list to ensure that the components were built
+in-order.
+
+Embedding Binary Data
+---------------------
+
+Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
+
+You can set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving the names of the files to embed in this way::
+
+  set(COMPONENT_EMBED_FILES server_root_cert.der)
+
+Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string::
+
+  set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
+
+The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
+
+  extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
+  extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
+
+The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
+
+For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
+
+
+Fully Overriding The Component Build Process
+--------------------------------------------
+
+Obviously, there are cases where all these recipes are insufficient for a
+certain component, for example when the component is basically a wrapper
+around another third-party component not originally intended to be
+compiled under this build system. In that case, it's possible to forego
+the esp-idf build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
+
+  # External build process for quirc, runs in source dir and
+  # produces libquirc.a
+  ExternalProject_Add(quirc_build
+      PREFIX ${COMPONENT_PATH}
+      SOURCE_DIR ${COMPONENT_PATH}/quirc
+      CONFIGURE_COMMAND ""
+      BUILD_IN_SOURCE 1
+      BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
+      INSTALL_COMMAND ""
+      )
+
+   # Add libquirc.a to the build process
+   #
+   add_library(quirc STATIC IMPORTED GLOBAL)
+   add_dependencies(quirc quirc_build)
+
+   set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
+        ${COMPONENT_PATH}/quirc/libquirc.a)
+   set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
+        ${COMPONENT_PATH}/quirc/lib)
+
+   set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
+        "${COMPONENT_PATH}/quirc/libquirc.a")
+
+(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
+
+- ExternalProject_Add defines an external build system.
+  - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
+  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
+  - Consult the ExternalProject_ documentation for more details about ``ExternalProject_Add()``
+
+- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
+- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
+
+ExternalProject dependencies, clean builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CMake has some unusual behaviour around external project builds:
+
+.. ADDITIONAL_MAKE_CLEAN_FILES_note:
+
+- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
+- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
+- Therefore, there are two alternative recommended ways to configure the external build command:
+  1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``ExternalProject_Add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
+  2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``ExternalProject_Add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
+
+The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
+
+.. _custom-sdkconfig-defaults-cmake:
+
+Custom sdkconfig defaults
+=========================
+
+For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
+
+To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
+
+
+Flash arguments
+===============
+
+There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
+
+After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
+
+- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
+- ``flash_app_args`` contains arguments to flash only the app.
+- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
+
+You can pass any of these flasher argument files to ``esptool.py`` as follows::
+
+  python esptool.py --chip esp32 write_flash @build/flash_project_args
+
+Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
+
+The build directory also contains a generated file ``project_description.json`` which contains project information, including project flash information, in the JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
+
+Building the Bootloader
+=======================
+
+The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
+
+The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
+
+The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
+
+Writing Pure CMake Components
+=============================
+
+The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
+
+However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
+
+Here is an example minimal "pure CMake" component CMakeLists file for a componen named ``json``::
+
+  add_library(json STATIC
+  cJSON/cJSON.c
+  cJSON/cJSON_Utils.c)
+
+  target_include_directories(json PUBLIC cJSON)
+
+- This is actually an equivalent version of the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
+- This file quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
+- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
+
+
+File Globbing & Incremental Builds
+==================================
+
+The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
+
+  set(COMPONENT_SRCDIRS library platform)
+
+The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
+
+  set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
+
+Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
+
+The tradeoff is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
+
+For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
+
+For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.)
+
+For project components (not part of ESP-IDF), there are a few options:
+
+- If keeping your project file in Git, ESP-IDF will automaticallytrack the Git revision and re-run CMake if the revision changes.
+- If some components are kept in a third git repo (not the project repo or ESP-IDF repo), you can add calls to the ``git_describe`` function to component CMakeLists to trigger re-runs of CMake.
+- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change.
+- Use ``COMPONENT_SRCS`` to list all source files in project components.
+
+The best option will depend on your particular project and its users.
+
+Migrating from ESP-IDF GNU Make System
+======================================
+
+Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_SRCS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
+
+However, some features are significantly different or removed in the CMake-based system:
+
+The following variables no longer exist in the CMake-based build system:
+
+- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
+- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the user. The name of the component library can no longer be overriden by the user.
+- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <language-variables-cmake>`_.
+- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
+- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
+- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically for files like linker scripts.
+- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo.
+- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
+- ``COMPONENT_OBJS``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``.
+- ``COMPONENT_EXTRA_CLEAN``: Set property `ADDITIONAL_MAKE_CLEAN_FILES` instead but note `CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See `Fully Overriding The Component CMakeLists` for full details.
+- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
+- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use CMake_ commands instead. See `Controlling Component Compilation`_.
+
+The following variables no longer have default values:
+
+- ``COMPONENT_SRCDIRS``
+- ``COMPONENT_ADD_INCLUDEDIRS``
+
+It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
+
+
+.. _esp-idf-template: https://github.com/espressif/esp-idf-template
+.. _cmake: https://cmake.org
+.. _ninja: https://ninja-build.org
+.. _esptool.py: https://github.com/espressif/esptool/#readme
+.. _CMake v3.5 documentation_: https://cmake.org/cmake/help/v3.5/index.html
+.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
+.. _add_compile_options-cmake: https://cmake.org/cmake/help/v3.5/command/add_compile_options.html
+.. _if-cmake: https://cmake.org/cmake/help/v3.5/command/if.html
+.. _string-cmake: https://cmake.org/cmake/help/v3.5/command/string.html
+.. _cmake-faq-generated-files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
+.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
+.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
+.. _language-variables-cmake: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
+.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
+.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
+.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
+.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
+.. _quirc: https://github.com/dlbeer/quirc
+
diff --git a/docs/en/api-guides/cmake-preview-index.rst b/docs/en/api-guides/cmake-preview-index.rst
new file mode 100644
index 000000000..22e94c67a
--- /dev/null
+++ b/docs/en/api-guides/cmake-preview-index.rst
@@ -0,0 +1,10 @@
+CMake-Based Build System Preview
+********************************
+
+.. toctree::
+   :maxdepth: 1
+
+   Getting Started <../get-started/index-cmake>
+   Linux Setup <../get-started/linux-setup-cmake>
+   Windows Setup <../get-started/windows-setup-cmake>
+   Build System Guide <build-system-cmake>
diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst
index bf0a2a018..6a13928fc 100644
--- a/docs/en/contribute/style-guide.rst
+++ b/docs/en/contribute/style-guide.rst
@@ -193,3 +193,5 @@ Language features
 
 To be written.
 
+.. _cmake-lint: https://github.com/richq/cmake-lint
+
diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
new file mode 100644
index 000000000..cdb120736
--- /dev/null
+++ b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
@@ -0,0 +1,66 @@
+Add IDF_PATH & idf.py PATH to User Profile
+==========================================
+
+.. note::
+   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<add-idf_path-to-profile>`.
+
+To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
+
+- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
+- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
+
+To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
+
+.. note::
+   If you only plan to use ``idf.py`` from the command line, and don't need integration with any IDEs, then you can skip setting ``IDF_PATH``. ``idf.py`` will use its own IDF directory as the default ``IDF_PATH``.
+
+.. _add-paths-to-profile-windows-cmake:
+
+Windows
+-------
+
+To edit Environment Variables on Windows 10, search for "Edit Environment Vartiables" under the Start menu.
+
+On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
+
+You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
+
+- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``.
+- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
+
+If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
+
+
+.. _add-idf_path-to-profile-linux-macos-cmake:
+
+Linux and MacOS
+---------------
+
+Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file::
+
+    export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:'$IDF_PATH/tools'"
+
+Log off and log in back to make this change effective.
+
+.. note::
+
+    If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
+
+Run the following command to check if ``IDF_PATH`` is set::
+
+    printenv IDF_PATH
+
+The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
+
+To verify idf.py is now on the ``PATH``, you can run the following::
+
+  which idf.py
+
+A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
+
+If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
+
+    export IDF_PATH=~/esp/esp-idf
+
+If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
index d8753a6bb..c96c2e546 100644
--- a/docs/en/get-started/establish-serial-connection.rst
+++ b/docs/en/get-started/establish-serial-connection.rst
@@ -125,5 +125,7 @@ If you see some legible log, it means serial connection is working and you are r
 
 If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
 
+(If you are following the CMake preview documentation, `go back to the CMake-specific section instead <:ref:get-started-configure>`.
+
 
 .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
diff --git a/docs/en/get-started/index-cmake.rst b/docs/en/get-started/index-cmake.rst
new file mode 100644
index 000000000..4eb2ef12f
--- /dev/null
+++ b/docs/en/get-started/index-cmake.rst
@@ -0,0 +1,346 @@
+***************************************
+Get Started with the CMake build system
+***************************************
+
+.. note::
+   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). For a stable experience, follow the :doc:`original (non-cmake) setup guide here<index>`.
+
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32.
+
+Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+
+
+Introduction
+============
+
+ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
+
+Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
+
+
+What You Need
+=============
+
+To develop applications for ESP32 you need:
+
+* **PC** loaded with either Windows, Linux or Mac operating system
+* **Toolchain** to build the **Application** for ESP32
+* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
+* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
+* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
+
+.. figure:: ../../_static/what-you-need.png
+    :align: center
+    :alt: Development of applications for ESP32
+    :figclass: align-center
+
+    Development of applications for ESP32
+
+Preparation of development environment consists of three steps:
+
+1. Setup of **Toolchain**
+2. Getting of **ESP-IDF** from GitHub
+3. Installation and configuration of **Eclipse**
+
+You may skip the last step, if you prefer to use different editor.
+
+Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
+
+1. Configuration of a **Project** and writing the code
+2. Compilation of the **Project** and linking it to build an **Application**
+3. Flashing (uploading) of the **Application** to **ESP32**
+4. Monitoring / debugging of the **Application**
+
+See instructions below that will walk you through these steps.
+
+
+Guides
+======
+
+If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
+
+.. toctree::
+    :maxdepth: 1
+
+    ESP32 DevKitC <get-started-devkitc>
+    ESP-WROVER-KIT <get-started-wrover-kit>
+    ESP32-PICO-KIT <get-started-pico-kit>
+
+If you have different board, move to sections below.
+
+
+.. _get-started-setup-toolchain-cmake:
+
+Setup Toolchain
+===============
+
+The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions. 
+
+.. toctree::
+    :hidden:
+
+    Windows <windows-setup-cmake>
+    Linux <linux-setup-cmake>
+    MacOS <macos-setup-cmake>
+
++-------------------+-------------------+-------------------+
+| |windows-logo|    | |linux-logo|      | |macos-logo|      |
++-------------------+-------------------+-------------------+
+| `Windows`_        | `Linux`_          | `Mac OS`_         |
++-------------------+-------------------+-------------------+
+
+.. |windows-logo| image:: ../../_static/windows-logo.png
+    :target: ../get-started/windows-setup-cmake.html
+
+.. |linux-logo| image:: ../../_static/linux-logo.png
+    :target: ../get-started/linux-setup-cmake.html
+
+.. |macos-logo| image:: ../../_static/macos-logo.png
+    :target: ../get-started/macos-setup-cmake.html
+
+.. _Windows: ../get-started/windows-setup-cmake.html
+.. _Linux: ../get-started/linux-setup-cmake.html
+.. _Mac OS: ../get-started/macos-setup-cmake.html
+
+.. note::
+
+    We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
+
+Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
+
+Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`.
+
+
+.. _get-started-get-esp-idf-cmake:
+
+Get ESP-IDF
+===========
+
+.. highlight:: bash
+
+Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
+
+    cd ~/esp
+    git clone --recursive https://github.com/espressif/esp-idf.git
+
+ESP-IDF will be downloaded into ``~/esp/esp-idf``.
+
+.. note::
+
+    Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
+
+        cd ~/esp/esp-idf
+        git submodule update --init
+
+
+.. _get-started-setup-path-cmake:
+
+Setup Paths for ESP-IDF
+=======================
+
+The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile-cmake`.
+
+
+.. _get-started-start-project-cmake:
+
+Start a Project
+===============
+
+Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
+
+Copy :example:`get-started/hello_world` to ``~/esp`` directory. You can do this via your operating system's file manager (like Windows Explorer). Or for Linux and MacOS, to do it from a Bash shell::
+
+    cd ~/esp
+    cp -r $IDF_PATH/examples/get-started/hello_world .
+
+
+You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
+
+.. important::
+
+    The esp-idf build system does not support spaces in paths to esp-idf or to projects.
+
+
+.. _get-started-connect-cmake:
+
+Connect
+=======
+
+You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
+
+
+.. _get-started-configure-cmake:
+
+Configure
+=========
+
+Open a terminal window (or a Windows Command Prompt), go to directory of the ``hello_world`` application by typing ``cd ~/esp/hello_world`` or ```cd \Users\esp\hello_world`` for Windows. Then start the project configuration utility ``menuconfig``::
+
+    cd ~/esp/hello_world
+    idf.py menuconfig
+
+.. note::
+   The first time you run ``idf.py`` for a given ESP-IDF project, CMake will run to configure the project. If any software tools or other requirements like environment variables are not configured correctly, this will produce a configuration error at this stage.
+
+.. note::
+    The previous (non-CMake) build system instructions would have told you to run ``make`` here, but the CMake-based system doesn't require use of ``make``.
+
+If previous steps have been done correctly, the following menu will be displayed:
+
+.. figure:: ../../_static/project-configuration.png
+    :align: center
+    :alt: Project configuration - Home window
+    :figclass: align-center
+
+    Project configuration - Home window
+
+In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
+
+.. note::
+
+   On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
+   (See :doc:`establish-serial-connection` for full details.)
+
+Here are couple of tips on navigation and use of ``menuconfig``:
+
+* Use up & down arrow keys to navigate the menu.
+* Use Enter key to go into a submenu, Escape key to go out or to exit.
+* Type ``?`` to see a help screen. Enter key exits the help screen.
+* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
+* Pressing ``?`` while highlighting a configuration item displays help about that item.
+* Type ``/`` to search the configuration items.
+
+.. _get-started-build-flash-cmake:
+
+Build and Flash
+===============
+
+Now you can build and flash the application. To build (but not flash) run::
+
+    idf.py build
+
+This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
+
+To flash these built firmware files to your ESP32 board, run::
+
+    idf.py -p <PORT> flash
+
+For ``<PORT>``, specify the connected ESP32's serial port like ``/dev/ttyUSB0`` (Linux), ``/dev/cu.USBx`` (MacOS) or ``COM1`` (Windows).
+
+.. highlight:: none
+
+::
+
+    esptool.py v2.0-beta2
+    Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
+    esptool.py v2.0-beta2
+    Connecting........___
+    Uploading stub...
+    Running stub...
+    Stub running...
+    Changing baud rate to 921600
+    Changed.
+    Attaching SPI flash...
+    Configuring flash size...
+    Auto-detected Flash size: 4MB
+    Flash params set to 0x0220
+    Compressed 11616 bytes to 6695...
+    Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
+    Hash of data verified.
+    Compressed 408096 bytes to 171625...
+    Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
+    Hash of data verified.
+    Compressed 3072 bytes to 82...
+    Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
+    Hash of data verified.
+
+    Leaving...
+    Hard resetting...
+
+If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
+
+.. note::
+   It's not necessary to run ``idf.py build`` before ``idf.py flash``, then flash step will automatically build the firmware if it needs to be built.
+
+.. _get-started-build-monitor-cmake:
+
+Monitor
+=======
+
+To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
+
+    $ idf.py monitor
+    --- idf_monitor on /dev/ttyUSB0 115200 ---
+    --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+    ets Jun  8 2016 00:22:57
+
+    rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+    ets Jun  8 2016 00:22:57
+    ...
+
+Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
+
+    ...
+    Hello world!
+    Restarting in 10 seconds...
+    I (211) cpu_start: Starting scheduler on APP CPU.
+    Restarting in 9 seconds...
+    Restarting in 8 seconds...
+    Restarting in 7 seconds...
+
+To exit the monitor use shortcut ``Ctrl+]``.
+
+.. note::
+
+    If instead of the messages above, you see a random garbage similar to::
+
+        e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
+        ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
+
+    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+
+To execute ``idf.py flash`` and then ``idf.py monitor``, you can run ``idf.py flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
+
+.. note::
+   At the moment not all of the idf_monitor shortcuts work correctly with the CMake-based build system.
+
+That's all what you need to get started with ESP32!
+
+Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
+
+
+Updating ESP-IDF
+================
+
+After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
+
+Another solution is to update only what has changed. This method is useful if you have slow connection to the GiHub. To do the update run the following commands::
+
+    cd ~/esp/esp-idf
+    git pull
+    git submodule update --init --recursive
+
+The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
+
+If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
+
+    cd ~/esp
+    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
+    cd esp-idf-v2.1/
+    git checkout v2.1
+    git submodule update --init --recursive
+
+After that remember to :doc:`add-idf_path-to-profile-cmake`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
+
+
+Related Documents
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    add-idf_path-to-profile-cmake
+    establish-serial-connection
+    make-project
+    idf-monitor
+    toolchain-setup-scratch
diff --git a/docs/en/get-started/linux-setup-cmake.rst b/docs/en/get-started/linux-setup-cmake.rst
new file mode 100644
index 000000000..2f54092fe
--- /dev/null
+++ b/docs/en/get-started/linux-setup-cmake.rst
@@ -0,0 +1,113 @@
+*************************************
+Setup for cmake on Linux
+*************************************
+
+.. note::
+   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<linux-setup>`.
+
+Install Prerequisites
+=====================
+
+To compile with ESP-IDF you need to get the following packages:
+
+- CentOS 7::
+
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build
+
+- Ubuntu and Debian::
+
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build
+
+- Arch::
+
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja
+
+.. note::
+    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
+
+Toolchain Setup
+===============
+
+ESP32 toolchain for Linux is available for download from Espressif website:
+
+- for 64-bit Linux:
+
+  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+- for 32-bit Linux:
+
+  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+1.  Download this file, then extract it in ``~/esp`` directory::
+
+        mkdir -p ~/esp
+        cd ~/esp
+        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+.. _setup-linux-toolchain-add-it-to-path:
+
+2.  The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
+
+    To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
+
+        export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+    Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
+
+        alias get_esp32='export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
+
+    Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
+
+    .. note::
+
+        If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
+
+3.  Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
+
+        printenv PATH
+
+    You are looking for similar result containing toolchain's path at the end of displayed string::
+
+        $ printenv PATH
+        /home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
+
+    Instead of ``/home/user-name`` there should be a home path specific to your installation.
+
+
+Permission issues /dev/ttyUSB0
+------------------------------
+
+With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
+
+
+Arch Linux Users
+----------------
+
+To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. 
+
+Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
+
+- https://aur.archlinux.org/packages/ncurses5-compat-libs/
+- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
+
+Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
+
+Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+
+Related Documents
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    linux-setup-scratch
+
+
+.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
diff --git a/docs/en/get-started/macos-setup-cmake.rst b/docs/en/get-started/macos-setup-cmake.rst
new file mode 100644
index 000000000..91a6c9dc4
--- /dev/null
+++ b/docs/en/get-started/macos-setup-cmake.rst
@@ -0,0 +1,61 @@
+*************************
+Setup for CMake on Mac OS
+*************************
+
+.. note::
+      The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is `here <:doc:macos-setup>`.
+
+Install Prerequisites
+=====================
+
+- install pip::
+
+    sudo easy_install pip
+
+- install pyserial::
+
+    sudo pip install pyserial
+
+- install CMake & Ninja build:
+
+  If you have HomeBrew, you can run::
+
+    brew install cmake ninja
+
+  Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation.
+
+Toolchain Setup
+===============
+
+ESP32 toolchain for macOS is available for download from Espressif website:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+Download this file, then extract it in ``~/esp`` directory::
+
+    mkdir -p ~/esp
+    cd ~/esp
+    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+.. _setup-macos-toolchain-add-it-to-path:
+
+The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
+
+To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
+
+    export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin
+
+Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
+
+    alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+.. _cmake: https://cmake.org/
+.. _ninja: https://ninja-build.org/
diff --git a/docs/en/get-started/windows-setup-cmake.rst b/docs/en/get-started/windows-setup-cmake.rst
new file mode 100644
index 000000000..ee9ebf3b3
--- /dev/null
+++ b/docs/en/get-started/windows-setup-cmake.rst
@@ -0,0 +1,78 @@
+***************************************
+Setup for cmake on Windows
+***************************************
+
+.. note::
+      The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<windows-setup>`.
+
+.. note::
+   Windows support in particular currently requires more manual installation of tools and setup of system Path than is planned for final release.
+
+Introduction
+============
+
+Unlike the conventional ESP-IDF make-based build environment, cmake does not require a GNU-compatible environment for building. You can build with cmake from Windows Command Prompt, or from an IDE with cmake support.
+
+Tools
+=====
+
+The following software packages need to be installed:
+
+cmake
+^^^^^
+
+Download the latest stable release of CMake_ for Windows and run the installer.
+
+When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
+
+
+Ninja build
+^^^^^^^^^^^
+
+Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
+
+The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory on your PATH.
+
+An easy directory to place ``ninja.exe`` is the CMake executable directory, as this is already on the PATH. This directory will be something like ``C:\Program Files\CMake\bin`` (look for the file ``cmake.exe`` in this directory to know it's the correct one).
+
+Python 2.x
+^^^^^^^^^^
+
+Download the latest Python_ 2.7 for Windows installer, and run it.
+
+The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
+
+Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
+
+  pip install pyserial
+
+
+Toolchain Setup
+===============
+
+Download the precompiled Windows toolchain from dl.espressif.com:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+
+Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
+
+Next, you need to add the ``bin`` subdirectory to your PATH. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
+
+Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
+
+Double-click the ``Path`` variable (either User or System Path, depending if you want other users to use the toolchain.) Go to the end of the value, and append ``;C:\Program Files\xtensa-esp32-elf\bin`` (or whatever the path to your toolchain ``bin`` directory is).
+
+.. note::
+   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+
+.. _cmake: https://cmake.org/download/
+.. _ninja: https://ninja-build.org/
+.. _ninja-dl: https://github.com/ninja-build/ninja/releases
+.. _Python: https://www.python.org/downloads/windows/
diff --git a/docs/en/index.rst b/docs/en/index.rst
index f3445d8dc..317eff85d 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -40,6 +40,7 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
    API Reference <api-reference/index>
    H/W Reference <hw-reference/index>
    API Guides <api-guides/index>
+   CMake Build System Preview <api-guides/cmake-preview-index>
    Contribute <contribute/index>
    Resources <resources>
    Copyrights <COPYRIGHT>
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 6e3d4ee51..95ddf07b6 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -133,20 +133,23 @@ function(components_finish_registration)
   # (we can't do this until all components are registered, because if(TARGET ...) won't work
   foreach(a ${COMPONENTS} ${CMAKE_PROJECT_NAME}.elf)
     if (TARGET ${a})
+      get_target_property(a_imported ${a} IMPORTED)
       get_target_property(a_type ${a} TYPE)
-      if (${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
-        foreach(b ${COMPONENTS})
-          if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
-            # Add all public compile options from b in a
-            target_include_directories(${a} PRIVATE
-              $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
-            target_compile_definitions(${a} PRIVATE
-              $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
-            target_compile_options(${a} PRIVATE
-              $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
-          endif()
-        endforeach(b)
-      endif(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
+      if (NOT a_imported)
+        if (${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
+          foreach(b ${COMPONENTS})
+            if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
+              # Add all public compile options from b in a
+              target_include_directories(${a} PRIVATE
+                $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
+              target_compile_definitions(${a} PRIVATE
+                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
+              target_compile_options(${a} PRIVATE
+                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
+            endif()
+          endforeach(b)
+        endif(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
+      endif(NOT a_imported)
 
       if (${a_type} MATCHES .+_LIBRARY)
         set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
@@ -166,4 +169,6 @@ function(components_finish_registration)
 
   target_link_libraries(${CMAKE_PROJECT_NAME}.elf ${COMPONENT_LIBRARIES})
 
+  message(STATUS "Component libraries: ${COMPONENT_LIBRARIES}")
+
 endfunction(components_finish_registration)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 9cab9bb56..9bea6f760 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -30,9 +30,6 @@ macro(idf_set_global_variables)
 
   # path to idf.py tool
   set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
-
-  # generate compile_commands.json
-  set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
 endmacro()
 
 # Add all the IDF global compiler & preprocessor options
@@ -161,6 +158,31 @@ endfunction(add_map_file)
 # Add argument file(s) for flashing the app, and for flashing the whole system
 function(add_flasher_argfile)
 
-  
-
 endfunction(add_flasher_argfile)
+
+# component_compile_options
+#
+# Wrapper around target_compile_options that passes the component name
+function(component_compile_options)
+  target_compile_options(${COMPONENT_NAME} PRIVATE ${ARGV})
+endfunction()
+
+# component_compile_definitions
+#
+# Wrapper around target_compile_definitions that passes the component name
+function(component_compile_definitions)
+  target_compile_definitions(${COMPONENT_NAME} PRIVATE ${ARGV})
+endfunction()
+
+# idf_get_git_revision
+#
+# Set global IDF_VER to the git revision of ESP-IDF.
+#
+# Running git_describe() here automatically triggers rebuilds
+# if the ESP-IDF git version changes
+function(idf_get_git_revision)
+  git_describe(IDF_VER "${IDF_PATH}")
+  add_definitions(-DIDF_VER=\"${IDF_VER}\")
+  git_submodule_check("${IDF_PATH}")
+  set(IDF_VER ${IDF_VER} PARENT_SCOPE)
+endfunction()
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 9f4d4ffa4..c2d809995 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -9,6 +9,8 @@ macro(kconfig_set_variables)
   set(SDKCONFIG_JSON ${CMAKE_BINARY_DIR}/sdkconfig.json)
 
   set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
+
+  set_default(SDKCONFIG_DEFAULTS "${SDKCONFIG}.defaults")
 endmacro()
 
 # Use the existing Makefile to build mconf (out of tree) when needed
@@ -46,8 +48,8 @@ function(kconfig_process_config)
     endif()
   endforeach(dir ${COMPONENT_PATHS})
 
-  if(EXISTS ${SDKCONFIG}.defaults)
-    set(defaults_arg --defaults "${SDKCONFIG}.defaults")
+  if(EXISTS ${SDKCONFIG_DEFAULTS})
+    set(defaults_arg --defaults "${SDKCONFIG_DEFAULTS}")
   endif()
 
   set(confgen_basecommand
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 7ed6b190d..0072c9372 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -44,6 +44,12 @@ macro(project name)
   # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
   components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
 
+  # Print list of components
+  string(REPLACE ";" " " COMPONENTS_SPACES "${COMPONENTS}")
+  message(STATUS "Component names: ${COMPONENTS_SPACES}")
+  unset(COMPONENTS_SPACES)
+  message(STATUS "Component paths: ${COMPONENT_PATHS}")
+
   kconfig_set_variables()
 
   kconfig_process_config()
@@ -59,17 +65,20 @@ macro(project name)
   # Declare the actual cmake-level project
   _project(${name} ASM C CXX)
 
-  # Verify the environment is configured correctly
+  # generate compile_commands.json (needs to come after project)
+  set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+
+   # Verify the environment is configured correctly
   idf_verify_environment()
 
   # Add some idf-wide definitions
   idf_set_global_compiler_options()
 
-  # Check git version (may trigger reruns of cmake)
-  # & set GIT_REVISION/IDF_VER variable
-  git_describe(GIT_REVISION)
-  add_definitions(-DIDF_VER=\"${GIT_REVISION}\")
-  git_submodule_check("${IDF_PATH}")
+  # Check git revision (may trigger reruns of cmake)
+  ##  sets IDF_VER to IDF git revision
+  idf_get_git_revision()
+  ## if project uses git, retrieve revision
+  git_describe(PROJECT_VER "${CMAKE_CURRENT_SOURCE_DIR}")
 
   # Include any top-level project_include.cmake files from components
   foreach(component ${COMPONENT_PATHS})
@@ -79,10 +88,12 @@ macro(project name)
   #
   # Add each component to the build as a library
   #
-  foreach(component ${COMPONENT_PATHS})
-    get_filename_component(component_name ${component} NAME)
-    add_subdirectory(${component} ${component_name})
+  foreach(COMPONENT_PATH ${COMPONENT_PATHS})
+    get_filename_component(COMPONENT_NAME ${COMPONENT_PATH} NAME)
+    add_subdirectory(${COMPONENT_PATH} ${COMPONENT_NAME})
   endforeach()
+  unset(COMPONENT_NAME)
+  unset(COMPONENT_PATH)
 
   #
   # Add the app executable to the build (has name of PROJECT.elf)
diff --git a/tools/cmake/project_description.json.in b/tools/cmake/project_description.json.in
index 21bbb3c87..2fb99c149 100644
--- a/tools/cmake/project_description.json.in
+++ b/tools/cmake/project_description.json.in
@@ -5,7 +5,7 @@
     "config_file":        "${SDKCONFIG}",
     "app_elf":            "${PROJECT_NAME}.elf",
     "app_bin":            "${PROJECT_NAME}.bin",
-    "git_revision":       "${GIT_REVISION}",
+    "git_revision":       "${IDF_VER}",
     "project_binaries":  {
         "bootloader":        [ "0x1000", "bootloader/bootloader.bin" ],
         "partition_table":   [ "0x8000", "partition_table/partition-table.bin" ],
diff --git a/tools/idf.py b/tools/idf.py
index fe118639c..dbffc2773 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -141,7 +141,11 @@ def _ensure_build_directory(args, always_run_cmake=False):
         if args.generator is None:
             args.generator = detect_cmake_generator()
         try:
-            _run_tool("cmake", ["cmake", "-G", args.generator, project_dir], cwd=args.build_dir)
+            cmake_args = ["cmake", "-G", args.generator]
+            if not args.no_warnings:
+                cmake_args += [ "--warn-uninitialized" ]
+            cmake_args += [ project_dir]
+            _run_tool("cmake", cmake_args, cwd=args.build_dir)
         except:
             # don't allow partially valid CMakeCache.txt files,
             # to keep the "should I run cmake?" logic simple
@@ -315,6 +319,7 @@ def main():
     parser.add_argument('-C', '--project-dir', help="Project directory", default=os.getcwd())
     parser.add_argument('-B', '--build-dir', help="Build directory", default=None)
     parser.add_argument('-G', '--generator', help="Cmake generator", choices=GENERATOR_CMDS.keys())
+    parser.add_argument('-n', '--no-warnings', help="Disable Cmake warnings")
     parser.add_argument('actions', help="Actions (build targets or other operations)", nargs='+',
                         choices=ACTIONS.keys())
 

From 15d5e8861883f0b20ddfdb118737cbe6c61dbe85 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 13:32:52 +1100
Subject: [PATCH 029/112] cmake: Automatically include ccache if it's on the
 path

---
 docs/en/get-started/linux-setup-cmake.rst | 6 +++---
 docs/en/get-started/macos-setup-cmake.rst | 3 +++
 examples/get-started/blink/CMakeLists.txt | 8 ++++++++
 tools/cmake/idf_functions.cmake           | 7 +++++++
 4 files changed, 21 insertions(+), 3 deletions(-)
 create mode 100644 examples/get-started/blink/CMakeLists.txt

diff --git a/docs/en/get-started/linux-setup-cmake.rst b/docs/en/get-started/linux-setup-cmake.rst
index 2f54092fe..2e3bbdbbe 100644
--- a/docs/en/get-started/linux-setup-cmake.rst
+++ b/docs/en/get-started/linux-setup-cmake.rst
@@ -12,15 +12,15 @@ To compile with ESP-IDF you need to get the following packages:
 
 - CentOS 7::
 
-    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
 
 - Ubuntu and Debian::
 
-    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
 
 .. note::
     CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
diff --git a/docs/en/get-started/macos-setup-cmake.rst b/docs/en/get-started/macos-setup-cmake.rst
index 91a6c9dc4..ce5623a53 100644
--- a/docs/en/get-started/macos-setup-cmake.rst
+++ b/docs/en/get-started/macos-setup-cmake.rst
@@ -24,6 +24,8 @@ Install Prerequisites
 
   Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation.
 
+- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew, this can be done via ``brew install ccache``.
+
 Toolchain Setup
 ===============
 
@@ -59,3 +61,4 @@ To carry on with development environment setup, proceed to section :ref:`get-sta
 
 .. _cmake: https://cmake.org/
 .. _ninja: https://ninja-build.org/
+.. _ccache: https://ccache.samba.org/
diff --git a/examples/get-started/blink/CMakeLists.txt b/examples/get-started/blink/CMakeLists.txt
new file mode 100644
index 000000000..56450928b
--- /dev/null
+++ b/examples/get-started/blink/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/blink.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(blink)
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 9bea6f760..2cb406e18 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -86,6 +86,13 @@ function(idf_set_global_compiler_options)
 
   add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
+    # Enable ccache if it's on the path
+    find_program(CCACHE_FOUND ccache)
+    if(CCACHE_FOUND)
+        message(STATUS "ccache will be used")
+        set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
+    endif()
+
 endfunction(idf_set_global_compiler_options)
 
 

From 88df8fd2934acd69fd4f0e8900e45700b2a387d5 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 15:45:30 +1100
Subject: [PATCH 030/112] cmake: Use cmake_lint project, tidy up all CMake
 source files

---
 .editorconfig                                 |   5 +
 components/aws_iot/CMakeLists.txt             |   6 +-
 components/bootloader/project_include.cmake   |  32 +-
 .../bootloader/subproject/CMakeLists.txt      |   4 +-
 components/bootloader_support/CMakeLists.txt  |   6 +-
 components/bt/CMakeLists.txt                  | 178 ++++++-----
 components/coap/CMakeLists.txt                |  39 ++-
 components/cxx/CMakeLists.txt                 |   2 +-
 components/esp32/CMakeLists.txt               | 131 +++++----
 components/esptool_py/CMakeLists.txt          |   8 +-
 components/esptool_py/project_include.cmake   |  35 ++-
 components/expat/CMakeLists.txt               |   8 +-
 components/heap/CMakeLists.txt                |  14 +-
 components/libsodium/CMakeLists.txt           | 156 +++++-----
 components/lwip/CMakeLists.txt                |  38 +--
 components/mbedtls/CMakeLists.txt             |   2 +-
 components/newlib/CMakeLists.txt              |  18 +-
 components/partition_table/CMakeLists.txt     |  40 +--
 components/spi_flash/CMakeLists.txt           |   8 +-
 docs/en/api-guides/build-system-cmake.rst     |  10 +-
 docs/en/contribute/style-guide.rst            |  14 +-
 .../get-started/hello_world/CMakeLists.txt    |   4 +-
 tools/cmake/components.cmake                  | 276 +++++++++---------
 tools/cmake/crosstool_version_check.cmake     |  15 +-
 tools/cmake/git_submodules.cmake              |  92 +++---
 tools/cmake/idf_functions.cmake               | 221 +++++++-------
 tools/cmake/kconfig.cmake                     | 161 +++++-----
 tools/cmake/project.cmake                     | 138 ++++-----
 tools/cmake/run_cmake_lint.sh                 |  32 ++
 tools/cmake/scripts/data_file_to_c.cmake      |   8 +-
 tools/cmake/toolchain-esp32.cmake             |  14 +-
 tools/cmake/utilities.cmake                   | 129 ++++----
 32 files changed, 962 insertions(+), 882 deletions(-)
 create mode 100755 tools/cmake/run_cmake_lint.sh

diff --git a/.editorconfig b/.editorconfig
index 15977c64e..edabd53b6 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -32,3 +32,8 @@ insert_final_newline = false
 
 [*.py]
 max_line_length = 119
+
+[{*.cmake,CMakeLists.txt}]
+indent_style = space
+indent_size = 4
+max_line_length = 120
diff --git a/components/aws_iot/CMakeLists.txt b/components/aws_iot/CMakeLists.txt
index 50219ab09..f8bfb26a2 100644
--- a/components/aws_iot/CMakeLists.txt
+++ b/components/aws_iot/CMakeLists.txt
@@ -1,8 +1,8 @@
-if(CONFIG_AWS_IOT_SDK)
+if(NOT CONFIG_AWS_IOT_SDK)
+    return()
+endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS "include aws-iot-device-sdk-embedded-C/include")
 set(COMPONENT_SRCDIRS "aws-iot-device-sdk-embedded-C/src port")
 
 register_component()
-
-endif(CONFIG_AWS_IOT_SDK)
diff --git a/components/bootloader/project_include.cmake b/components/bootloader/project_include.cmake
index cef56f47e..3d583eefb 100644
--- a/components/bootloader/project_include.cmake
+++ b/components/bootloader/project_include.cmake
@@ -1,5 +1,5 @@
 if(BOOTLOADER_BUILD)
-  return()  # don't keep recursing!
+    return()  # don't keep recursing!
 endif()
 
 # Glue to build the bootloader subproject binary as an external
@@ -8,24 +8,26 @@ endif()
 #
 set(bootloader_build_dir "${CMAKE_BINARY_DIR}/bootloader")
 set(bootloader_binary_files
-  "${bootloader_build_dir}/bootloader.elf"
-  "${bootloader_build_dir}/bootloader.bin"
-  "${bootloader_build_dir}/bootloader.map"
-  )
+    "${bootloader_build_dir}/bootloader.elf"
+    "${bootloader_build_dir}/bootloader.bin"
+    "${bootloader_build_dir}/bootloader.map"
+    )
 
-ExternalProject_Add(bootloader
-  # TODO: support overriding the bootloader in COMPONENT_PATHS
-  SOURCE_DIR "${IDF_PATH}/components/bootloader/subproject"
-  BINARY_DIR "${bootloader_build_dir}"
-  CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH="${IDF_PATH}"
-  INSTALL_COMMAND ""
-  BUILD_ALWAYS 1  # no easy way around this...
-  BUILD_BYPRODUCTS ${bootloader_binary_files}
-  )
+externalproject_add(bootloader
+    # TODO: support overriding the bootloader in COMPONENT_PATHS
+    SOURCE_DIR "${IDF_PATH}/components/bootloader/subproject"
+    BINARY_DIR "${bootloader_build_dir}"
+    CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH="${IDF_PATH}"
+    INSTALL_COMMAND ""
+    BUILD_ALWAYS 1  # no easy way around this...
+    BUILD_BYPRODUCTS ${bootloader_binary_files}
+    )
 
 # this is a hack due to an (annoying) shortcoming in cmake, it can't
 # extend the 'clean' target to the external project
 # see thread: https://cmake.org/pipermail/cmake/2016-December/064660.html
 #
 # So for now we just have the top-level build remove the final build products...
-set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES ${bootloader_binary_files})
+set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY
+    ADDITIONAL_MAKE_CLEAN_FILES
+    ${bootloader_binary_files})
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index e5d2c18bf..9d99e6e0c 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -1,7 +1,8 @@
 cmake_minimum_required(VERSION 3.5)
 
 if(NOT SDKCONFIG)
-  message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed in by the parent build process.")
+    message(FATAL_ERROR "Bootloader subproject expects the SDKCONFIG variable to be passed "
+        "in by the parent build process.")
 endif()
 
 set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash micro-ecc soc)
@@ -18,4 +19,3 @@ target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
 target_link_libraries(bootloader.elf "-T esp32.bootloader.rom.ld")
 target_link_libraries(bootloader.elf "${BOOTLOADER_LINKER_ARGS}")
 target_link_libraries(bootloader.elf gcc)
-
diff --git a/components/bootloader_support/CMakeLists.txt b/components/bootloader_support/CMakeLists.txt
index 1e5c52fb8..6df7b24db 100644
--- a/components/bootloader_support/CMakeLists.txt
+++ b/components/bootloader_support/CMakeLists.txt
@@ -1,10 +1,10 @@
 set(COMPONENT_SRCDIRS "src")
 
 if(${BOOTLOADER_BUILD})
-  set(COMPONENT_ADD_INCLUDEDIRS "include include_priv")
+    set(COMPONENT_ADD_INCLUDEDIRS "include include_priv")
 else()
-  set(COMPONENT_ADD_INCLUDEDIRS "include")
-  set(COMPONENT_PRIV_INCLUDEDIRS "include_priv")
+    set(COMPONENT_ADD_INCLUDEDIRS "include")
+    set(COMPONENT_PRIV_INCLUDEDIRS "include_priv")
 endif()
 
 register_component()
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index ec18c3375..f50c58ab0 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -1,99 +1,97 @@
-if(CONFIG_BT_ENABLED)
+if(NOT CONFIG_BT_ENABLED)
+    return()
+endif()
 
-  set(COMPONENT_SRCDIRS .)
-  set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_SRCDIRS .)
+set(COMPONENT_ADD_INCLUDEDIRS include)
 
-  target_link_libraries("-L ${CMAKE_CURRENT_LIST_DIR}/lib")
-  target_link_libraries(bt btdm_app)
+target_link_libraries("-L ${CMAKE_CURRENT_LIST_DIR}/lib")
+target_link_libraries(bt btdm_app)
 
-  if(CONFIG_BLUEDROID_ENABLED)
+if(CONFIG_BLUEDROID_ENABLED)
 
     set(COMPONENT_ADD_INCLUDEDIRS ${COMPONENT_ADD_INCLUDEDIRS}
-      bluedroid/bta/include
-      bluedroid/bta/sys/include
-      bluedroid/btcore/include
-      bluedroid/device/include
-      bluedroid/gki/include
-      bluedroid/hci/include
-      bluedroid/osi/include
-      bluedroid/utils/include
-      bluedroid/external/sbc/decoder/include
-      bluedroid/btc/core/include
-      bluedroid/btc/profile/esp/blufi/include
-      bluedroid/btc/profile/esp/include
-      bluedroid/btc/profile/std/gatt/include
-      bluedroid/btc/profile/std/gap/include
-      bluedroid/btc/profile/std/a2dp/include
-      bluedroid/btc/profile/std/include
-      bluedroid/btc/include
-      bluedroid/btif/include
-      bluedroid/stack/btm/include
-      bluedroid/stack/btu/include
-      bluedroid/stack/gap/include
-      bluedroid/stack/gatt/include
-      bluedroid/stack/hcic/include
-      bluedroid/stack/l2cap/include
-      bluedroid/stack/sdp/include
-      bluedroid/stack/smp/include
-      bluedroid/stack/avct/include
-      bluedroid/stack/avrc/include
-      bluedroid/stack/avdt/include
-      bluedroid/stack/a2dp/include
-      bluedroid/stack/rfcomm/include
-      bluedroid/stack/include
-      bluedroid/utils/include
-      bluedroid/api/include
-      bluedroid/include)
+        bluedroid/bta/include
+        bluedroid/bta/sys/include
+        bluedroid/btcore/include
+        bluedroid/device/include
+        bluedroid/gki/include
+        bluedroid/hci/include
+        bluedroid/osi/include
+        bluedroid/utils/include
+        bluedroid/external/sbc/decoder/include
+        bluedroid/btc/core/include
+        bluedroid/btc/profile/esp/blufi/include
+        bluedroid/btc/profile/esp/include
+        bluedroid/btc/profile/std/gatt/include
+        bluedroid/btc/profile/std/gap/include
+        bluedroid/btc/profile/std/a2dp/include
+        bluedroid/btc/profile/std/include
+        bluedroid/btc/include
+        bluedroid/btif/include
+        bluedroid/stack/btm/include
+        bluedroid/stack/btu/include
+        bluedroid/stack/gap/include
+        bluedroid/stack/gatt/include
+        bluedroid/stack/hcic/include
+        bluedroid/stack/l2cap/include
+        bluedroid/stack/sdp/include
+        bluedroid/stack/smp/include
+        bluedroid/stack/avct/include
+        bluedroid/stack/avrc/include
+        bluedroid/stack/avdt/include
+        bluedroid/stack/a2dp/include
+        bluedroid/stack/rfcomm/include
+        bluedroid/stack/include
+        bluedroid/utils/include
+        bluedroid/api/include
+        bluedroid/include)
 
     set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
-      bluedroid/bta/dm
-      bluedroid/bta/gatt
-      bluedroid/bta/hh
-      bluedroid/bta/sdp
-      bluedroid/bta/av
-      bluedroid/bta/ar
-      bluedroid/bta/sys
-      bluedroid/bta/jv
-      bluedroid/bta
-      bluedroid/btcore
-      bluedroid/btif
-      bluedroid/device
-      bluedroid/gki
-      bluedroid/hci
-      bluedroid/main
-      bluedroid/osi
-      bluedroid/external/sbc/decoder/srce
-      bluedroid/btc/core
-      bluedroid/btc/profile/esp/blufi
-      bluedroid/btc/profile/std/gap
-      bluedroid/btc/profile/std/gatt
-      bluedroid/btc/profile/std/a2dp
-      bluedroid/btc/profile/std/avrc
-      bluedroid/btc/profile/std/spp
-      bluedroid/btc/profile
-      bluedroid/stack/btm
-      bluedroid/stack/btu
-      bluedroid/stack/gap
-      bluedroid/stack/gatt
-      bluedroid/stack/hcic
-      bluedroid/stack/include
-      bluedroid/stack/l2cap
-      bluedroid/stack/sdp
-      bluedroid/stack/smp
-      bluedroid/stack/avct
-      bluedroid/stack/avrc
-      bluedroid/stack/avdt
-      bluedroid/stack/a2dp
-      bluedroid/stack/rfcomm
-      bluedroid/stack
-      bluedroid/utils
-      bluedroid/api
-      bluedroid)
-
-  endif(CONFIG_BLUEDROID_ENABLED)
-
-  register_component()
-
-endif(CONFIG_BT_ENABLED)
+        bluedroid/bta/dm
+        bluedroid/bta/gatt
+        bluedroid/bta/hh
+        bluedroid/bta/sdp
+        bluedroid/bta/av
+        bluedroid/bta/ar
+        bluedroid/bta/sys
+        bluedroid/bta/jv
+        bluedroid/bta
+        bluedroid/btcore
+        bluedroid/btif
+        bluedroid/device
+        bluedroid/gki
+        bluedroid/hci
+        bluedroid/main
+        bluedroid/osi
+        bluedroid/external/sbc/decoder/srce
+        bluedroid/btc/core
+        bluedroid/btc/profile/esp/blufi
+        bluedroid/btc/profile/std/gap
+        bluedroid/btc/profile/std/gatt
+        bluedroid/btc/profile/std/a2dp
+        bluedroid/btc/profile/std/avrc
+        bluedroid/btc/profile/std/spp
+        bluedroid/btc/profile
+        bluedroid/stack/btm
+        bluedroid/stack/btu
+        bluedroid/stack/gap
+        bluedroid/stack/gatt
+        bluedroid/stack/hcic
+        bluedroid/stack/include
+        bluedroid/stack/l2cap
+        bluedroid/stack/sdp
+        bluedroid/stack/smp
+        bluedroid/stack/avct
+        bluedroid/stack/avrc
+        bluedroid/stack/avdt
+        bluedroid/stack/a2dp
+        bluedroid/stack/rfcomm
+        bluedroid/stack
+        bluedroid/utils
+        bluedroid/api
+        bluedroid)
 
+endif()
 
+register_component()
diff --git a/components/coap/CMakeLists.txt b/components/coap/CMakeLists.txt
index 2f51d6c0a..cadd463fa 100644
--- a/components/coap/CMakeLists.txt
+++ b/components/coap/CMakeLists.txt
@@ -1,31 +1,28 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include port/include/coap libcoap/include libcoap/include/coap)
 
 set(COMPONENT_SRCS
-  libcoap/src/address.c
-  libcoap/src/async.c
-  libcoap/src/block.c
-  libcoap/src/coap_time.c
-  libcoap/src/debug.c
-  libcoap/src/encode.c
-  libcoap/src/hashkey.c
-  libcoap/src/mem.c
-  libcoap/src/net.c
-  libcoap/src/option.c
-  libcoap/src/pdu.c
-  libcoap/src/resource.c
-  libcoap/src/str.c
-  libcoap/src/subscribe.c
-  libcoap/src/uri.c
-  port/coap_io_socket.c
-  )
+    libcoap/src/address.c
+    libcoap/src/async.c
+    libcoap/src/block.c
+    libcoap/src/coap_time.c
+    libcoap/src/debug.c
+    libcoap/src/encode.c
+    libcoap/src/hashkey.c
+    libcoap/src/mem.c
+    libcoap/src/net.c
+    libcoap/src/option.c
+    libcoap/src/pdu.c
+    libcoap/src/resource.c
+    libcoap/src/str.c
+    libcoap/src/subscribe.c
+    libcoap/src/uri.c
+    port/coap_io_socket.c
+    )
 
 register_component()
 
 # Needed for coap headers in public builds, also.
 #
 # TODO: find a way to move this to a port header
-target_compile_definitions(coap PUBLIC
-	WITH_POSIX
-)
-
+target_compile_definitions(coap PUBLIC WITH_POSIX)
 
diff --git a/components/cxx/CMakeLists.txt b/components/cxx/CMakeLists.txt
index c7341ceab..255f4f3fd 100644
--- a/components/cxx/CMakeLists.txt
+++ b/components/cxx/CMakeLists.txt
@@ -6,5 +6,5 @@ target_link_libraries(cxx stdc++)
 target_link_libraries(cxx "-u __cxa_guard_dummy")
 
 if(NOT CONFIG_CXX_EXCEPTIONS)
-  target_link_libraries(cxx "-u __cxx_fatal_exception")
+    target_link_libraries(cxx "-u __cxx_fatal_exception")
 endif()
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 963f8802b..31b6ce546 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -1,77 +1,86 @@
 if(BOOTLOADER_BUILD)
-  # For bootloader, all we need from esp32 is headers
-  add_library(esp32 INTERFACE)
-  target_include_directories(esp32 INTERFACE include)
+    # For bootloader, all we need from esp32 is headers
+    add_library(esp32 INTERFACE)
+    target_include_directories(esp32 INTERFACE include)
 
-  # as cmake won't attach linker args to a header-only library, attach
-  # linker args directly to the bootloader.elf
-  set(BOOTLOADER_LINKER_ARGS "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld -T esp32.rom.ld -Tesp32.rom.spiram_incompatible_fns.ld -T esp32.peripherals.ld" PARENT_SCOPE)
+    # as cmake won't attach linker args to a header-only library, attach
+    # linker args directly to the bootloader.elf
+    set(BOOTLOADER_LINKER_ARGS
+        "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld"
+        "-T esp32.rom.ld"
+        "-T esp32.rom.spiram_incompatible_fns.ld"
+        "-T esp32.peripherals.ld"
+        PARENT_SCOPE)
 
 else()
-  # Regular app build
+    # Regular app build
 
-  set(COMPONENT_SRCDIRS ". hwcrypto")
-  set(COMPONENT_ADD_INCLUDEDIRS "include")
+    set(COMPONENT_SRCDIRS ". hwcrypto")
+    set(COMPONENT_ADD_INCLUDEDIRS "include")
 
-  register_component()
+    register_component()
 
-  target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
-  if(NOT CONFIG_NO_BLOBS)
-    target_link_libraries(esp32 coexist core espnow net80211 phy pp rtc smartconfig wpa2 wpa wps)
-  endif()
-  target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld")
-  target_link_libraries(esp32 "-T ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
-  target_link_libraries(esp32 "-T esp32.common.ld")
-  target_link_libraries(esp32 "-T esp32.rom.ld")
-  target_link_libraries(esp32 "-T esp32.peripherals.ld")
+    target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
+    if(NOT CONFIG_NO_BLOBS)
+        target_link_libraries(esp32 coexist core espnow net80211 phy pp rtc smartconfig wpa2 wpa wps)
+    endif()
+    target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld")
+    target_link_libraries(esp32 "-T ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
+    target_link_libraries(esp32 "-T esp32.common.ld")
+    target_link_libraries(esp32 "-T esp32.rom.ld")
+    target_link_libraries(esp32 "-T esp32.peripherals.ld")
 
-  if(CONFIG_SPIRAM_CACHE_WORKAROUND)
-    target_link_libraries(esp32 ${CMAKE_CURRENT_SOURCE_DIR}/libstdc++-psram-workaround.a)
-  else()
-    target_link_libraries(esp32 "-T esp32.rom.spiram_incompatible_fns.ld")
-  endif()
+    if(CONFIG_SPIRAM_CACHE_WORKAROUND)
+        target_link_libraries(esp32 ${CMAKE_CURRENT_SOURCE_DIR}/libstdc++-psram-workaround.a)
+    else()
+        target_link_libraries(esp32 "-T esp32.rom.spiram_incompatible_fns.ld")
+    endif()
 
-  if(CONFIG_NEWLIB_NANO_FORMAT)
-    target_link_libraries(esp32 "-T esp32.rom.nanofmt.ld")
-  endif()
+    if(CONFIG_NEWLIB_NANO_FORMAT)
+        target_link_libraries(esp32 "-T esp32.rom.nanofmt.ld")
+    endif()
 
-  if(NOT CONFIG_SPI_FLASH_ROM_DRIVER_PATCH)
-    target_link_libraries(esp32 "-T esp32.rom.spiflash.ld")
-  endif()
+    if(NOT CONFIG_SPI_FLASH_ROM_DRIVER_PATCH)
+        target_link_libraries(esp32 "-T esp32.rom.spiflash.ld")
+    endif()
 
-  target_link_libraries(esp32 "${CMAKE_CURRENT_SOURCE_DIR}/libhal.a")
-  target_link_libraries(esp32 gcc)
-  target_link_libraries(esp32 "-u call_user_start_cpu0")
+    target_link_libraries(esp32 "${CMAKE_CURRENT_SOURCE_DIR}/libhal.a")
+    target_link_libraries(esp32 gcc)
+    target_link_libraries(esp32 "-u call_user_start_cpu0")
 
-  #ld_include_panic_highint_hdl is added as an undefined symbol because otherwise the
-#linker will ignore panic_highint_hdl.S as it has no other files depending on any
-#symbols in it.
-  target_link_libraries(esp32 "-u ld_include_panic_highint_hdl")
+    #ld_include_panic_highint_hdl is added as an undefined symbol because otherwise the
+    #linker will ignore panic_highint_hdl.S as it has no other files depending on any
+    #symbols in it.
+    target_link_libraries(esp32 "-u ld_include_panic_highint_hdl")
 
-  # Preprocess esp32.ld linker script to include configuration, becomes esp32_out.ld
-  set(LD_DIR ${CMAKE_CURRENT_SOURCE_DIR}/ld)
-  add_custom_command(
-    OUTPUT esp32_out.ld
-    COMMAND "${CMAKE_C_COMPILER}" -C -P -x c -E -o esp32_out.ld -I ${CMAKE_BINARY_DIR} ${LD_DIR}/esp32.ld
-    MAIN_DEPENDENCY ${LD_DIR}/esp32.ld
-    COMMENT "Generating linker script..."
-    VERBATIM)
-  add_custom_target(esp32_linker_script DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld)
-  add_dependencies(esp32 esp32_linker_script)
-
-  if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
-    set(PHY_INIT_DATA_BIN phy_init_data.bin)
-
-    # To get the phy_init_data.bin file, compile phy_init_data.h as a C file and then objcopy the object file to a raw binary
+    # Preprocess esp32.ld linker script to include configuration, becomes esp32_out.ld
+    set(LD_DIR ${CMAKE_CURRENT_SOURCE_DIR}/ld)
     add_custom_command(
-      OUTPUT ${PHY_INIT_DATA_BIN}
-      DEPENDS ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
-      COMMAND ${CMAKE_C_COMPILER} -x c -c -o phy_init_data.obj -I ${CMAKE_CURRENT_LIST_DIR} -I ${CMAKE_CURRENT_LIST_DIR}/include -I ${CMAKE_BINARY_DIR} ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
-      COMMAND ${CMAKE_OBJCOPY} -O binary phy_init_data.obj ${PHY_INIT_DATA_BIN}
-      )
-    add_custom_target(phy_init_data ALL DEPENDS ${PHY_INIT_DATA_BIN})
-    add_dependencies(flash phy_init_data)
+        OUTPUT esp32_out.ld
+        COMMAND "${CMAKE_C_COMPILER}" -C -P -x c -E -o esp32_out.ld -I ${CMAKE_BINARY_DIR} ${LD_DIR}/esp32.ld
+        MAIN_DEPENDENCY ${LD_DIR}/esp32.ld
+        COMMENT "Generating linker script..."
+        VERBATIM)
+    add_custom_target(esp32_linker_script DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld)
+    add_dependencies(esp32 esp32_linker_script)
 
-  endif(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+    if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+        set(PHY_INIT_DATA_BIN phy_init_data.bin)
 
-endif(BOOTLOADER_BUILD)
+        # To get the phy_init_data.bin file, compile phy_init_data.h as a C file and then objcopy
+        # the object file to a raw binary
+        add_custom_command(
+            OUTPUT ${PHY_INIT_DATA_BIN}
+            DEPENDS ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
+            COMMAND ${CMAKE_C_COMPILER} -x c -c
+            -I ${CMAKE_CURRENT_LIST_DIR} -I ${CMAKE_CURRENT_LIST_DIR}/include -I ${CMAKE_BINARY_DIR}
+            -o phy_init_data.obj
+            ${CMAKE_CURRENT_LIST_DIR}/phy_init_data.h
+            COMMAND ${CMAKE_OBJCOPY} -O binary phy_init_data.obj ${PHY_INIT_DATA_BIN}
+            )
+        add_custom_target(phy_init_data ALL DEPENDS ${PHY_INIT_DATA_BIN})
+        add_dependencies(flash phy_init_data)
+
+    endif()
+
+endif()
diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
index d8d64344c..5a7d23efd 100644
--- a/components/esptool_py/CMakeLists.txt
+++ b/components/esptool_py/CMakeLists.txt
@@ -2,8 +2,8 @@ register_config_only_component()
 
 # Generate pre-canned flasher args files suitable for passing to esptool.py
 foreach(part project app bootloader)
-configure_file(
-  "${CMAKE_CURRENT_LIST_DIR}/flash_${part}_args.in"
-  "${CMAKE_BINARY_DIR}/flash_${part}_args"
-  )
+    configure_file(
+        "${CMAKE_CURRENT_LIST_DIR}/flash_${part}_args.in"
+        "${CMAKE_BINARY_DIR}/flash_${part}_args"
+        )
 endforeach()
diff --git a/components/esptool_py/project_include.cmake b/components/esptool_py/project_include.cmake
index 04efbb7e7..31ce13d66 100644
--- a/components/esptool_py/project_include.cmake
+++ b/components/esptool_py/project_include.cmake
@@ -10,38 +10,43 @@ set(ESPFLASHSIZE ${CONFIG_ESPTOOLPY_FLASHSIZE})
 
 set(ESPTOOLPY_SERIAL "${ESPTOOLPY}" --port "${ESPPORT}" --baud ${ESPBAUD})
 
-set(ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS --flash_mode ${ESPFLASHMODE} --flash_freq ${ESPFLASHFREQ} --flash_size ${ESPFLASHSIZE})
+set(ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS
+    --flash_mode ${ESPFLASHMODE}
+    --flash_freq ${ESPFLASHFREQ}
+    --flash_size ${ESPFLASHSIZE}
+    )
 
 if(CONFIG_ESPTOOLPY_FLASHSIZE_DETECT)
-  # Set ESPFLASHSIZE to 'detect' *after* elf2image options are generated,
-  # as elf2image can't have 'detect' as an option...
-  set(ESPFLASHSIZE detect)
+    # Set ESPFLASHSIZE to 'detect' *after* elf2image options are generated,
+    # as elf2image can't have 'detect' as an option...
+    set(ESPFLASHSIZE detect)
 endif()
 
 # Set variables if the PHY data partition is in the flash
-if (CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
-  set(PHY_PARTITION_OFFSET   ${CONFIG_PHY_DATA_OFFSET})
-  set(PHY_PARTITION_BIN_FILE "esp32/phy_init_data.bin")
+if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+    set(PHY_PARTITION_OFFSET   ${CONFIG_PHY_DATA_OFFSET})
+    set(PHY_PARTITION_BIN_FILE "esp32/phy_init_data.bin")
 endif()
 
 #
 # Add 'app.bin' target - generates with elf2image
 #
 add_custom_command(OUTPUT "${PROJECT_NAME}.bin"
-  COMMAND ${ESPTOOLPY} elf2image ${ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS} -o "${PROJECT_NAME}.bin" "${PROJECT_NAME}.elf"
-  DEPENDS ${PROJECT_NAME}.elf
-  VERBATIM
-  )
+    COMMAND ${ESPTOOLPY} elf2image ${ESPTOOLPY_ELF2IMAGE_FLASH_OPTIONS} -o "${PROJECT_NAME}.bin" "${PROJECT_NAME}.elf"
+    DEPENDS ${PROJECT_NAME}.elf
+    VERBATIM
+    )
 add_custom_target(app ALL DEPENDS "${PROJECT_NAME}.bin")
 
 #
 # Add 'flash' target - not all build systems can run this directly
 #
 function(esptool_py_custom_target target_name flasher_filename dependencies)
-  add_custom_target(${target_name} DEPENDS ${dependencies}
-    COMMAND ${ESPTOOLPY} -p ${CONFIG_ESPTOOLPY_PORT} -b ${CONFIG_ESPTOOLPY_BAUD} write_flash @flash_${flasher_filename}_args
-    WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
-    )
+    add_custom_target(${target_name} DEPENDS ${dependencies}
+        COMMAND ${ESPTOOLPY} -p ${CONFIG_ESPTOOLPY_PORT} -b ${CONFIG_ESPTOOLPY_BAUD}
+        write_flash @flash_${flasher_filename}_args
+        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+        )
 endfunction()
 
 esptool_py_custom_target(flash project "app;partition_table;bootloader")
diff --git a/components/expat/CMakeLists.txt b/components/expat/CMakeLists.txt
index 169dd4f89..9e77a825c 100644
--- a/components/expat/CMakeLists.txt
+++ b/components/expat/CMakeLists.txt
@@ -7,7 +7,7 @@ component_compile_definitions(HAVE_EXPAT_CONFIG_H)
 
 # patch around warnings in third-party files
 set_source_files_properties(
-  library/xmlparse.c
-  PROPERTIES COMPILE_FLAGS
-  -Wno-unused-function
-  )
+    library/xmlparse.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-unused-function
+    )
diff --git a/components/heap/CMakeLists.txt b/components/heap/CMakeLists.txt
index 6fd009ae9..08e78e845 100644
--- a/components/heap/CMakeLists.txt
+++ b/components/heap/CMakeLists.txt
@@ -1,7 +1,7 @@
 set(COMPONENT_SRCS heap_caps_init.c heap_caps.c multi_heap.c heap_trace.c)
 
 if(NOT CONFIG_HEAP_POISONING_DISABLED)
-  set(COMPONENT_SRCS ${COMPONENT_SRCS} multi_heap_poisoning.c)
+    set(COMPONENT_SRCS ${COMPONENT_SRCS} multi_heap_poisoning.c)
 endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS "include")
@@ -9,11 +9,11 @@ set(COMPONENT_ADD_INCLUDEDIRS "include")
 register_component()
 
 if(CONFIG_HEAP_TRACING)
-  set(WRAP_FUNCTIONS
-    calloc malloc free realloc heap_caps_malloc heap_caps_free heap_caps_realloc)
+    set(WRAP_FUNCTIONS
+        calloc malloc free realloc heap_caps_malloc heap_caps_free heap_caps_realloc)
 
-  foreach(wrap ${WRAP_FUNCTIONS})
-    target_link_libraries(heap "-Wl,--wrap=${wrap}")
-  endforeach()
+    foreach(wrap ${WRAP_FUNCTIONS})
+        target_link_libraries(heap "-Wl,--wrap=${wrap}")
+    endforeach()
 
-endif(CONFIG_HEAP_TRACING)
+endif()
diff --git a/components/libsodium/CMakeLists.txt b/components/libsodium/CMakeLists.txt
index f35f19c22..48e5a3f69 100644
--- a/components/libsodium/CMakeLists.txt
+++ b/components/libsodium/CMakeLists.txt
@@ -1,70 +1,70 @@
 set(SRC libsodium/src/libsodium)
 
 set(COMPONENT_SRCDIRS
-  port
+    port
 
-  # Derived from libsodium/src/libsodium/Makefile.am
-  # (ignoring the !MINIMAL set)
-  ${SRC}/crypto_aead/chacha20poly1305/sodium
-  ${SRC}/crypto_aead/xchacha20poly1305/sodium
-  ${SRC}/crypto_auth
-  ${SRC}/crypto_auth/hmacsha256
-  ${SRC}/crypto_auth/hmacsha512
-  ${SRC}/crypto_auth/hmacsha512256
-  ${SRC}/crypto_box
-  ${SRC}/crypto_box/curve25519xsalsa20poly1305
-  ${SRC}/crypto_core/curve25519/ref10
-  ${SRC}/crypto_core/hchacha20
-  ${SRC}/crypto_core/hsalsa20/ref2
-  ${SRC}/crypto_core/hsalsa20
-  ${SRC}/crypto_core/salsa/ref
-  ${SRC}/crypto_generichash
-  ${SRC}/crypto_generichash/blake2b
-  ${SRC}/crypto_generichash/blake2b/ref
-  ${SRC}/crypto_hash
-  ${SRC}/crypto_hash/sha256
-  ${SRC}/crypto_hash/sha512
-  ${SRC}/crypto_kdf/blake2b
-  ${SRC}/crypto_kdf
-  ${SRC}/crypto_kx
-  ${SRC}/crypto_onetimeauth
-  ${SRC}/crypto_onetimeauth/poly1305
-  ${SRC}/crypto_onetimeauth/poly1305/donna
-  ${SRC}/crypto_pwhash/argon2
-  ${SRC}/crypto_pwhash
-  ${SRC}/crypto_pwhash/scryptsalsa208sha256
-  ${SRC}/crypto_pwhash/scryptsalsa208sha256/nosse
-  ${SRC}/crypto_scalarmult
-  ${SRC}/crypto_scalarmult/curve25519
-  ${SRC}/crypto_scalarmult/curve25519/ref10
-  ${SRC}/crypto_secretbox
-  ${SRC}/crypto_secretbox/xsalsa20poly1305
-  ${SRC}/crypto_shorthash
-  ${SRC}/crypto_shorthash/siphash24
-  ${SRC}/crypto_shorthash/siphash24/ref
-  ${SRC}/crypto_sign
-  ${SRC}/crypto_sign/ed25519
-  ${SRC}/crypto_sign/ed25519/ref10
-  ${SRC}/crypto_stream/chacha20
-  ${SRC}/crypto_stream/chacha20/ref
-  ${SRC}/crypto_stream
-  ${SRC}/crypto_stream/salsa20
-  ${SRC}/crypto_stream/salsa20/ref
-  ${SRC}/crypto_stream/xsalsa20
-  ${SRC}/crypto_verify/sodium
-  ${SRC}/randombytes
-  ${SRC}/sodium
-  )
+    # Derived from libsodium/src/libsodium/Makefile.am
+    # (ignoring the !MINIMAL set)
+    ${SRC}/crypto_aead/chacha20poly1305/sodium
+    ${SRC}/crypto_aead/xchacha20poly1305/sodium
+    ${SRC}/crypto_auth
+    ${SRC}/crypto_auth/hmacsha256
+    ${SRC}/crypto_auth/hmacsha512
+    ${SRC}/crypto_auth/hmacsha512256
+    ${SRC}/crypto_box
+    ${SRC}/crypto_box/curve25519xsalsa20poly1305
+    ${SRC}/crypto_core/curve25519/ref10
+    ${SRC}/crypto_core/hchacha20
+    ${SRC}/crypto_core/hsalsa20/ref2
+    ${SRC}/crypto_core/hsalsa20
+    ${SRC}/crypto_core/salsa/ref
+    ${SRC}/crypto_generichash
+    ${SRC}/crypto_generichash/blake2b
+    ${SRC}/crypto_generichash/blake2b/ref
+    ${SRC}/crypto_hash
+    ${SRC}/crypto_hash/sha256
+    ${SRC}/crypto_hash/sha512
+    ${SRC}/crypto_kdf/blake2b
+    ${SRC}/crypto_kdf
+    ${SRC}/crypto_kx
+    ${SRC}/crypto_onetimeauth
+    ${SRC}/crypto_onetimeauth/poly1305
+    ${SRC}/crypto_onetimeauth/poly1305/donna
+    ${SRC}/crypto_pwhash/argon2
+    ${SRC}/crypto_pwhash
+    ${SRC}/crypto_pwhash/scryptsalsa208sha256
+    ${SRC}/crypto_pwhash/scryptsalsa208sha256/nosse
+    ${SRC}/crypto_scalarmult
+    ${SRC}/crypto_scalarmult/curve25519
+    ${SRC}/crypto_scalarmult/curve25519/ref10
+    ${SRC}/crypto_secretbox
+    ${SRC}/crypto_secretbox/xsalsa20poly1305
+    ${SRC}/crypto_shorthash
+    ${SRC}/crypto_shorthash/siphash24
+    ${SRC}/crypto_shorthash/siphash24/ref
+    ${SRC}/crypto_sign
+    ${SRC}/crypto_sign/ed25519
+    ${SRC}/crypto_sign/ed25519/ref10
+    ${SRC}/crypto_stream/chacha20
+    ${SRC}/crypto_stream/chacha20/ref
+    ${SRC}/crypto_stream
+    ${SRC}/crypto_stream/salsa20
+    ${SRC}/crypto_stream/salsa20/ref
+    ${SRC}/crypto_stream/xsalsa20
+    ${SRC}/crypto_verify/sodium
+    ${SRC}/randombytes
+    ${SRC}/sodium
+    )
 
 if(CONFIG_LIBSODIUM_USE_MBEDTLS_SHA)
-  set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
-    port/crypto_hash_mbedtls
-    )
+    set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+        port/crypto_hash_mbedtls
+        )
 else()
-  set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
-    ${SRC}/crypto_hash/sha256/cp
-    ${SRC}/crypto_hash/sha512/cp
-    )
+    set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+        ${SRC}/crypto_hash/sha256/cp
+        ${SRC}/crypto_hash/sha512/cp
+        )
 endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS ${SRC}/include port_include)
@@ -73,28 +73,26 @@ set(COMPONENT_PRIV_INCLUDEDIRS ${SRC}/include/sodium port_include/sodium port)
 register_component()
 
 component_compile_definitions(
-	CONFIGURED
-	NATIVE_LITTLE_ENDIAN
-	HAVE_WEAK_SYMBOLS
-	__STDC_LIMIT_MACROS
-	__STDC_CONSTANT_MACROS
-)
+    CONFIGURED
+    NATIVE_LITTLE_ENDIAN
+    HAVE_WEAK_SYMBOLS
+    __STDC_LIMIT_MACROS
+    __STDC_CONSTANT_MACROS
+    )
 
 component_compile_options(-Wno-unknown-pragmas)
 
 # patch around warnings in third-party files
 set_source_files_properties(
-  ${SRC}/crypto_pwhash/argon2/argon2-fill-block-ref.c
-  ${SRC}/crypto_pwhash/argon2/pwhash_argon2i.c
-  ${SRC}/crypto_pwhash/argon2/argon2-core.c
-  ${SRC}/crypto_pwhash/scryptsalsa208sha256/pwhash_scryptsalsa208sha256.c
-  PROPERTIES COMPILE_FLAGS
-  -Wno-type-limits
-  )
+    ${SRC}/crypto_pwhash/argon2/argon2-fill-block-ref.c
+    ${SRC}/crypto_pwhash/argon2/pwhash_argon2i.c
+    ${SRC}/crypto_pwhash/argon2/argon2-core.c
+    ${SRC}/crypto_pwhash/scryptsalsa208sha256/pwhash_scryptsalsa208sha256.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-type-limits
+    )
 set_source_files_properties(
-  ${SRC}/sodium/utils.c
-  PROPERTIES COMPILE_FLAGS
-  -Wno-unused-variable
-  )
-
-
+    ${SRC}/sodium/utils.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-unused-variable
+    )
diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
index 64dffb41d..5474c4daa 100644
--- a/components/lwip/CMakeLists.txt
+++ b/components/lwip/CMakeLists.txt
@@ -1,20 +1,20 @@
 set(COMPONENT_ADD_INCLUDEDIRS
-	include/lwip
-	include/lwip/port
-	include/lwip/posix
-	apps/ping
+    include/lwip
+    include/lwip/port
+    include/lwip/posix
+    apps/ping
     )
 
 if(CONFIG_PPP_SUPPORT)
-set(LWIP_PPP_DIRS netif/ppp/polarssl netif/ppp)
+    set(LWIP_PPP_DIRS netif/ppp/polarssl netif/ppp)
 endif()
 
 set(COMPONENT_SRCDIRS
-	api
-	apps apps/sntp apps/ping
-	core core/ipv4 core/ipv6
-	${LWIP_PPP_DIRS} netif
-	port/freertos port/netif port/debug port)
+    api
+    apps apps/sntp apps/ping
+    core core/ipv4 core/ipv6
+    ${LWIP_PPP_DIRS} netif
+    port/freertos port/netif port/debug port)
 
 register_component()
 
@@ -22,14 +22,14 @@ component_compile_options(-Wno-address)
 
 # patch around warnings in third-party files
 set_source_files_properties(api/tcpip.c
-  PROPERTIES COMPILE_FLAGS
-  -Wno-unused-variable
-  )
+    PROPERTIES COMPILE_FLAGS
+    -Wno-unused-variable
+    )
 set_source_files_properties(core/pbuf.c core/tcp_in.c
-  PROPERTIES COMPILE_FLAGS
-  -Wno-unused-but-set-variable
-  )
+    PROPERTIES COMPILE_FLAGS
+    -Wno-unused-but-set-variable
+    )
 set_source_files_properties(apps/dhcpserver.c
-  PROPERTIES COMPILE_FLAGS
-  "-Wno-unused-variable -Wno-unused-but-set-variable -Wno-type-limits"
-  )
+    PROPERTIES COMPILE_FLAGS
+    "-Wno-unused-variable -Wno-unused-but-set-variable -Wno-type-limits"
+    )
diff --git a/components/mbedtls/CMakeLists.txt b/components/mbedtls/CMakeLists.txt
index 293ad00ce..56dfce17c 100644
--- a/components/mbedtls/CMakeLists.txt
+++ b/components/mbedtls/CMakeLists.txt
@@ -4,5 +4,5 @@ set(COMPONENT_SRCDIRS library port)
 register_component()
 
 target_compile_definitions(mbedtls PUBLIC
-	-DMBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
+    -DMBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
 )
diff --git a/components/newlib/CMakeLists.txt b/components/newlib/CMakeLists.txt
index 09f26c46a..c92518deb 100644
--- a/components/newlib/CMakeLists.txt
+++ b/components/newlib/CMakeLists.txt
@@ -2,18 +2,18 @@ set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS platform_include include)
 
 if(CONFIG_SPIRAM_CACHE_WORKAROUND)
-  set(LIBC c-psram-workaround)
-  set(LIBM m-psram-workaround)
+    set(LIBC c-psram-workaround)
+    set(LIBM m-psram-workaround)
 else()
 
-  if(CONFIG_NEWLIB_NANO_FORMAT)
-    set(LIBC c_nano)
-  else()
-    set(LIBC c)
-  endif(CONFIG_NEWLIB_NANO_FORMAT)
+    if(CONFIG_NEWLIB_NANO_FORMAT)
+        set(LIBC c_nano)
+    else()
+        set(LIBC c)
+    endif()
 
-  set(LIBM m)
-endif(CONFIG_SPIRAM_CACHE_WORKAROUND)
+    set(LIBM m)
+endif()
 
 register_component()
 
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index c0b2a3833..87f12da94 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -3,21 +3,21 @@ set(partition_table_offset 0x8000)
 # Set partition_csv to the configured partition source file
 #
 if(CONFIG_PARTITION_TABLE_CUSTOM)
-  # Custom filename expands any path relative to the project
-  get_filename_component(partition_csv "${CONFIG_PARTITION_TABLE_CUSTOM}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+    # Custom filename expands any path relative to the project
+    get_filename_component(partition_csv "${CONFIG_PARTITION_TABLE_CUSTOM}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
 else()
-  # Other .csv files are always in the component directory
-  set(partition_csv "${CMAKE_CURRENT_SOURCE_DIR}/${CONFIG_PARTITION_TABLE_FILENAME}")
+    # Other .csv files are always in the component directory
+    set(partition_csv "${CMAKE_CURRENT_SOURCE_DIR}/${CONFIG_PARTITION_TABLE_FILENAME}")
 endif()
 
 if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
-  set(unsigned_partition_bin "partition-table-unsigned.bin")
-  set(final_partition_bin "partition-table.bin")
-  set(final_partition_target "sign_partition_table")
+    set(unsigned_partition_bin "partition-table-unsigned.bin")
+    set(final_partition_bin "partition-table.bin")
+    set(final_partition_target "sign_partition_table")
 else()
-  set(unsigned_partition_bin "partition-table.bin")
-  set(final_partition_bin "partition-table.bin")
-  set(final_partition_target "build_partition_table")
+    set(unsigned_partition_bin "partition-table.bin")
+    set(final_partition_bin "partition-table.bin")
+    set(final_partition_target "build_partition_table")
 endif()
 
 if(CONFIG_PARTITION_TABLE_MD5)
@@ -36,18 +36,24 @@ add_custom_command(OUTPUT "${unsigned_partition_bin}"
 
 # Add signing steps
 if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
-  get_filename_component(secure_boot_signing_key "${CONFIG_SECURE_BOOT_SIGNING_KEY}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+    get_filename_component(secure_boot_signing_key
+        "${CONFIG_SECURE_BOOT_SIGNING_KEY}"
+        ABSOLUTE BASE_DIR "${PROJECT_PATH}")
 
-  add_custom_command(OUTPUT "${final_partition_bin}"
-    COMMAND "${PYTHON}" "${ESPSECUREPY}" sign_data --keyfile "${secure_boot_signing_key}" -o "${final_partition_bin}" "${unsigned_partition_bin}"
-    DEPENDS "${unsigned_partition_bin}"
-    VERBATIM)
+    add_custom_command(OUTPUT "${final_partition_bin}"
+        COMMAND "${PYTHON}" "${ESPSECUREPY}" sign_data --keyfile "${secure_boot_signing_key}"
+        -o "${final_partition_bin}" "${unsigned_partition_bin}"
+        DEPENDS "${unsigned_partition_bin}"
+        VERBATIM)
 
 endif()
 
 add_custom_target(partition_table ALL DEPENDS "${final_partition_bin}")
 
-# Use global properties ESPTOOL_WRITE_FLASH_ARGS to pass this info to build hte list of esptool write arguments for flashing
-set_property(GLOBAL APPEND_STRING PROPERTY ESPTOOL_WRITE_FLASH_ARGS "${partition_table_offset} ${final_partition_bin} ")
+# Use global properties ESPTOOL_WRITE_FLASH_ARGS to pass this info to build
+# the list of esptool write arguments for flashing
+set_property(GLOBAL APPEND_STRING PROPERTY
+    ESPTOOL_WRITE_FLASH_ARGS
+    "${partition_table_offset} ${final_partition_bin} ")
 
 register_config_only_component()
diff --git a/components/spi_flash/CMakeLists.txt b/components/spi_flash/CMakeLists.txt
index 2b2622261..f64a6ec11 100644
--- a/components/spi_flash/CMakeLists.txt
+++ b/components/spi_flash/CMakeLists.txt
@@ -1,9 +1,9 @@
 if(BOOTLOADER_BUILD)
-  # Bootloader needs SPIUnlock from this file, but doesn't
-  # need other parts of this component
-  set(COMPONENT_SRCS spi_flash_rom_patch.c)
+    # Bootloader needs SPIUnlock from this file, but doesn't
+    # need other parts of this component
+    set(COMPONENT_SRCS spi_flash_rom_patch.c)
 else()
-  set(COMPONENT_SRCDIRS .)
+    set(COMPONENT_SRCDIRS .)
 endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS include)
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index 607fb2e3f..c363058c6 100644
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -564,7 +564,7 @@ the esp-idf build system entirely by using a CMake feature called ExternalProjec
 
   # External build process for quirc, runs in source dir and
   # produces libquirc.a
-  ExternalProject_Add(quirc_build
+  externalproject_add(quirc_build
       PREFIX ${COMPONENT_PATH}
       SOURCE_DIR ${COMPONENT_PATH}/quirc
       CONFIGURE_COMMAND ""
@@ -588,10 +588,10 @@ the esp-idf build system entirely by using a CMake feature called ExternalProjec
 
 (The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
 
-- ExternalProject_Add defines an external build system.
+- ``externalproject_add`` defines an external build system.
   - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
   - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
-  - Consult the ExternalProject_ documentation for more details about ``ExternalProject_Add()``
+  - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
 
 - The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
 - Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
@@ -606,8 +606,8 @@ CMake has some unusual behaviour around external project builds:
 - `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
 - However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
 - Therefore, there are two alternative recommended ways to configure the external build command:
-  1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``ExternalProject_Add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
-  2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``ExternalProject_Add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
+  1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
+  2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
 
 The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
 
diff --git a/docs/en/contribute/style-guide.rst b/docs/en/contribute/style-guide.rst
index 6a13928fc..cceacf2a1 100644
--- a/docs/en/contribute/style-guide.rst
+++ b/docs/en/contribute/style-guide.rst
@@ -170,6 +170,19 @@ To re-format a file, run::
     tools/format.sh components/my_component/file.c
 
 
+CMake Code Style
+----------------
+
+- Indent with four spaces.
+- Maximum line length 120 characters. When splitting lines, try to
+  focus on readability where possible (for example, by pairing up
+  keyword/argument pairs on individual lines).
+- Don't put anything in the optional parentheses after ``endforeach()``, ``endif()``, etc.
+- Use lowercase (``with_underscores``) for command, function, and macro names.
+- For locally scoped variables, use lowercase (``with_underscores``).
+- For globally scoped variables, use uppercase (``WITH_UNDERSCORES``).
+- Otherwise follow the defaults of the cmake-lint_ project.
+
 Configuring the code style for a project using EditorConfig
 -----------------------------------------------------------
 
@@ -194,4 +207,3 @@ Language features
 To be written.
 
 .. _cmake-lint: https://github.com/richq/cmake-lint
-
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
index e0b4ccdef..cd8c56e58 100644
--- a/examples/get-started/hello_world/CMakeLists.txt
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -1,5 +1,5 @@
-# The following five lines of boilerplate have to be in your project's CMakeLists
-# in this exact order for cmake to work correctly
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
 set(MAIN_SRCS main/hello_world_main.c)
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 95ddf07b6..8c6518703 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -5,170 +5,174 @@
 # component_paths contains only unique component names. Directories
 # earlier in the component_dirs list take precedence.
 function(components_find_all component_dirs filter_names component_paths component_names)
-  # component_dirs entries can be files or lists of files
-  set(paths "")
-  set(names "")
+    # component_dirs entries can be files or lists of files
+    set(paths "")
+    set(names "")
 
-  # start by expanding the component_dirs list with all subdirectories
-  foreach(dir ${component_dirs})
-    # Iterate any subdirectories for values
-    file(GLOB subdirs LIST_DIRECTORIES true "${dir}/*")
-    foreach(subdir ${subdirs})
-      set(component_dirs "${component_dirs};${subdir}")
+    # start by expanding the component_dirs list with all subdirectories
+    foreach(dir ${component_dirs})
+        # Iterate any subdirectories for values
+        file(GLOB subdirs LIST_DIRECTORIES true "${dir}/*")
+        foreach(subdir ${subdirs})
+            set(component_dirs "${component_dirs};${subdir}")
+        endforeach()
     endforeach()
-  endforeach()
 
-  # Look for a component in each component_dirs entry
-  foreach(dir ${component_dirs})
-    file(GLOB component "${dir}/CMakeLists.txt")
-    if(component)
-      get_filename_component(component "${component}" DIRECTORY)
-      get_filename_component(name "${component}" NAME)
-      if(NOT filter_names OR (name IN_LIST filter_names))
-        if(NOT name IN_LIST names)
-          set(names "${names};${name}")
-          set(paths "${paths};${component}")
+    # Look for a component in each component_dirs entry
+    foreach(dir ${component_dirs})
+        file(GLOB component "${dir}/CMakeLists.txt")
+        if(component)
+            get_filename_component(component "${component}" DIRECTORY)
+            get_filename_component(name "${component}" NAME)
+            if(NOT filter_names OR (name IN_LIST filter_names))
+                if(NOT name IN_LIST names)
+                    set(names "${names};${name}")
+                    set(paths "${paths};${component}")
+                endif()
+            endif()
+
+        else()  # no CMakeLists.txt file
+            # test for legacy component.mk and warn
+            file(GLOB legacy_component "${dir}/component.mk")
+            if(legacy_component)
+                get_filename_component(legacy_component "${legacy_component}" DIRECTORY)
+                message(WARNING "Component ${legacy_component} contains old-style component.mk but no CMakeLists.txt. "
+                    "Component will be skipped.")
+            endif()
         endif()
-      endif()
 
-    else()  # no CMakeLists.txt file
-      # test for legacy component.mk and warn
-      file(GLOB legacy_component "${dir}/component.mk")
-      if(legacy_component)
-        get_filename_component(legacy_component "${legacy_component}" DIRECTORY)
-        message(WARNING "Component ${legacy_component} contains old-style component.mk but no CMakeLists.txt. Component will be skipped.")
-      endif()
-    endif(component)
+    endforeach()
 
-  endforeach(dir ${component_dirs})
-
-  set(${component_paths} ${paths} PARENT_SCOPE)
-  set(${component_names} ${names} PARENT_SCOPE)
-endfunction(components_find_all)
+    set(${component_paths} ${paths} PARENT_SCOPE)
+    set(${component_names} ${names} PARENT_SCOPE)
+endfunction()
 
 
 # Add a component to the build, using the COMPONENT variables defined
 # in the parent
 #
 function(register_component)
-  get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
-  get_filename_component(component ${component_dir} NAME)
+    get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
+    get_filename_component(component ${component_dir} NAME)
 
-  spaces2list(COMPONENT_SRCDIRS)
-  spaces2list(COMPONENT_ADD_INCLUDEDIRS)
+    spaces2list(COMPONENT_SRCDIRS)
+    spaces2list(COMPONENT_ADD_INCLUDEDIRS)
 
-  # Add to COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
-  if(NOT COMPONENT_SRCS)
-    foreach(dir ${COMPONENT_SRCDIRS})
-      get_filename_component(abs_dir ${dir} ABSOLUTE BASE_DIR ${component_dir})
-      if(NOT IS_DIRECTORY ${abs_dir})
-        message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' does not exist")
-      endif()
+    # Add to COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
+    if(NOT COMPONENT_SRCS)
+        foreach(dir ${COMPONENT_SRCDIRS})
+            get_filename_component(abs_dir ${dir} ABSOLUTE BASE_DIR ${component_dir})
+            if(NOT IS_DIRECTORY ${abs_dir})
+                message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' does not exist")
+            endif()
 
-      file(GLOB matches "${abs_dir}/*.c" "${abs_dir}/*.cpp" "${abs_dir}/*.S")
-      if(matches)
-        list(SORT matches)
-        set(COMPONENT_SRCS "${COMPONENT_SRCS};${matches}")
-      else()
-        message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' contains no source files")
-      endif(matches)
-    endforeach()
-  endif()
+            file(GLOB matches "${abs_dir}/*.c" "${abs_dir}/*.cpp" "${abs_dir}/*.S")
+            if(matches)
+                list(SORT matches)
+                set(COMPONENT_SRCS "${COMPONENT_SRCS};${matches}")
+            else()
+                message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_SRCDIRS entry '${dir}' has no source files")
+            endif()
+        endforeach()
+    endif()
 
-  # add public includes from other components when building this component
-  if(COMPONENT_SRCS OR embed_binaries)
-    add_library(${component} STATIC ${COMPONENT_SRCS})
-    set(include_type PUBLIC)
-  else()
-    add_library(${component} INTERFACE) # header-only component
-    set(include_type INTERFACE)
-  endif()
-
-  # binaries to embed directly in library
-  spaces2list(COMPONENT_EMBED_FILES)
-  spaces2list(COMPONENT_EMBED_TXTFILES)
-  foreach(embed_data ${COMPONENT_EMBED_FILES} ${COMPONENT_EMBED_TXTFILES})
-    if (embed_data IN_LIST COMPONENT_EMBED_TXTFILES)
-      set(embed_type "TEXT")
+    # add public includes from other components when building this component
+    if(COMPONENT_SRCS OR embed_binaries)
+        add_library(${component} STATIC ${COMPONENT_SRCS})
+        set(include_type PUBLIC)
     else()
-      set(embed_type "BINARY")
-    endif()
-    target_add_binary_data("${component}" "${embed_data}" "${embed_type}")
-  endforeach()
-
-  # add public includes
-  foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
-    get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
-    if(NOT IS_DIRECTORY ${abs_dir})
-      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_ADD_INCLUDEDIRS entry '${include_dir}' does not exist")
-    endif()
-    target_include_directories(${component} ${include_type} ${abs_dir})
-  endforeach()
-
-  # add private includes
-  foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
-    if (${include_type} STREQUAL INTERFACE)
-      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE} sets no component source files but sets COMPONENT_PRIV_INCLUDEDIRS")
+        add_library(${component} INTERFACE) # header-only component
+        set(include_type INTERFACE)
     endif()
 
-    get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
-    if(NOT IS_DIRECTORY ${abs_dir})
-      message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: COMPONENT_PRIV_INCLUDEDIRS entry '${niclude_dir}' does not exist")
-    endif()
-    target_include_directories(${component} PRIVATE ${abs_dir})
-  endforeach()
+    # binaries to embed directly in library
+    spaces2list(COMPONENT_EMBED_FILES)
+    spaces2list(COMPONENT_EMBED_TXTFILES)
+    foreach(embed_data ${COMPONENT_EMBED_FILES} ${COMPONENT_EMBED_TXTFILES})
+        if(embed_data IN_LIST COMPONENT_EMBED_TXTFILES)
+            set(embed_type "TEXT")
+        else()
+            set(embed_type "BINARY")
+        endif()
+        target_add_binary_data("${component}" "${embed_data}" "${embed_type}")
+    endforeach()
 
-endfunction(register_component)
+    # add public includes
+    foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
+        get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+        if(NOT IS_DIRECTORY ${abs_dir})
+            message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: "
+                "COMPONENT_ADD_INCLUDEDIRS entry '${include_dir}' not found")
+        endif()
+        target_include_directories(${component} ${include_type} ${abs_dir})
+    endforeach()
+
+    # add private includes
+    foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
+        if(${include_type} STREQUAL INTERFACE)
+            message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE} "
+                "sets no component source files but sets COMPONENT_PRIV_INCLUDEDIRS")
+        endif()
+
+        get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
+        if(NOT IS_DIRECTORY ${abs_dir})
+            message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE}: "
+                "COMPONENT_PRIV_INCLUDEDIRS entry '${include_dir}' does not exist")
+        endif()
+        target_include_directories(${component} PRIVATE ${abs_dir})
+    endforeach()
+
+endfunction()
 
 function(register_config_only_component)
-  get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
-  get_filename_component(component ${component_dir} NAME)
+    get_filename_component(component_dir ${CMAKE_CURRENT_LIST_FILE} DIRECTORY)
+    get_filename_component(component ${component_dir} NAME)
 
-  # No-op for now...
-endfunction(register_config_only_component)
+    # No-op for now...
+endfunction()
 
 function(components_finish_registration)
-  # each component should see the include directories of each other
-  #
-  # (we can't do this until all components are registered, because if(TARGET ...) won't work
-  foreach(a ${COMPONENTS} ${CMAKE_PROJECT_NAME}.elf)
-    if (TARGET ${a})
-      get_target_property(a_imported ${a} IMPORTED)
-      get_target_property(a_type ${a} TYPE)
-      if (NOT a_imported)
-        if (${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
-          foreach(b ${COMPONENTS})
-            if (TARGET ${b} AND NOT ${a} STREQUAL ${b})
-              # Add all public compile options from b in a
-              target_include_directories(${a} PRIVATE
-                $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
-              target_compile_definitions(${a} PRIVATE
-                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
-              target_compile_options(${a} PRIVATE
-                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
+    # each component should see the include directories of each other
+    #
+    # (we can't do this until all components are registered, because if(TARGET ...) won't work
+    foreach(a ${COMPONENTS} ${CMAKE_PROJECT_NAME}.elf)
+        if(TARGET ${a})
+            get_target_property(a_imported ${a} IMPORTED)
+            get_target_property(a_type ${a} TYPE)
+            if(NOT a_imported)
+                if(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
+                    foreach(b ${COMPONENTS})
+                        if(TARGET ${b} AND NOT ${a} STREQUAL ${b})
+                            # Add all public compile options from b in a
+                            target_include_directories(${a} PRIVATE
+                                $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
+                            target_compile_definitions(${a} PRIVATE
+                                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
+                            target_compile_options(${a} PRIVATE
+                                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
+                        endif()
+                    endforeach(b)
+                endif()
             endif()
-          endforeach(b)
-        endif(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
-      endif(NOT a_imported)
 
-      if (${a_type} MATCHES .+_LIBRARY)
-        set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
-      endif()
-    endif()
-  endforeach()
+            if(${a_type} MATCHES .+_LIBRARY)
+                set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
+            endif()
+        endif()
+    endforeach()
 
-  # Embedded binary & text files
-  spaces2list(COMPONENT_EMBED_FILES)
-  foreach(embed_src ${COMPONENT_EMBED_FILES})
-    target_add_binary_data(${component} "${embed_src}" BINARY)
-  endforeach()
-  spaces2list(COMPONENT_EMBED_TXTFILES)
-  foreach(embed_src ${COMPONENT_EMBED_TXTFILES})
-    target_add_binary_data(${component} "${embed_src}" TEXT)
-  endforeach()
+    # Embedded binary & text files
+    spaces2list(COMPONENT_EMBED_FILES)
+    foreach(embed_src ${COMPONENT_EMBED_FILES})
+        target_add_binary_data(${component} "${embed_src}" BINARY)
+    endforeach()
+    spaces2list(COMPONENT_EMBED_TXTFILES)
+    foreach(embed_src ${COMPONENT_EMBED_TXTFILES})
+        target_add_binary_data(${component} "${embed_src}" TEXT)
+    endforeach()
 
-  target_link_libraries(${CMAKE_PROJECT_NAME}.elf ${COMPONENT_LIBRARIES})
+    target_link_libraries(${CMAKE_PROJECT_NAME}.elf ${COMPONENT_LIBRARIES})
 
-  message(STATUS "Component libraries: ${COMPONENT_LIBRARIES}")
+    message(STATUS "Component libraries: ${COMPONENT_LIBRARIES}")
 
-endfunction(components_finish_registration)
+endfunction()
diff --git a/tools/cmake/crosstool_version_check.cmake b/tools/cmake/crosstool_version_check.cmake
index ed518907e..f55f121d3 100644
--- a/tools/cmake/crosstool_version_check.cmake
+++ b/tools/cmake/crosstool_version_check.cmake
@@ -4,16 +4,17 @@
 set(ctng_version_warning "Check Getting Started documentation or proceed at own risk.")
 
 function(gcc_version_check expected_gcc_version)
-  if(NOT "${CMAKE_C_COMPILER_VERSION}" STREQUAL "${expected_gcc_version}")
-    message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} version ${CMAKE_C_COMPILER_VERSION} is not the supported version ${expected_gcc_version}. ${ctng_version_warning}")
-  endif()
+    if(NOT "${CMAKE_C_COMPILER_VERSION}" STREQUAL "${expected_gcc_version}")
+        message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} version ${CMAKE_C_COMPILER_VERSION} "
+            "is not the supported version ${expected_gcc_version}. ${ctng_version_warning}")
+    endif()
 endfunction()
 
 function(crosstool_version_check expected_ctng_version)
-  execute_process(
-    COMMAND ${CMAKE_C_COMPILER} -v
-    ERROR_VARIABLE toolchain_stderr
-    OUTPUT_QUIET)
+    execute_process(
+        COMMAND ${CMAKE_C_COMPILER} -v
+        ERROR_VARIABLE toolchain_stderr
+        OUTPUT_QUIET)
 
     string(REGEX MATCH "crosstool-ng-[0-9a-g\\.-]+" ctng_version "${toolchain_stderr}")
     string(REPLACE "crosstool-ng-" "" ctng_version "${ctng_version}")
diff --git a/tools/cmake/git_submodules.cmake b/tools/cmake/git_submodules.cmake
index 73e1f35f9..09098b24a 100644
--- a/tools/cmake/git_submodules.cmake
+++ b/tools/cmake/git_submodules.cmake
@@ -1,61 +1,61 @@
 find_package(Git)
 
 if(NOT GIT_FOUND)
-  message(WARNING "Git executable was not found. Git submodule checks will not be executed. If you have any build issues at all, start by adding git executable to the PATH and rerun cmake to not see this warning again.")
+    message(WARNING "Git executable was not found. Git submodule checks will not be executed. "
+        "If you have any build issues at all, start by adding git executable to the PATH and "
+        "rerun cmake to not see this warning again.")
 
-  function(git_submodule_check root_path)
-    # no-op
-  endfunction()
-else(NOT GIT_FOUND)
+    function(git_submodule_check root_path)
+        # no-op
+    endfunction()
+else()
 
-  function(git_submodule_check root_path)
+    function(git_submodule_check root_path)
 
-    execute_process(
-      COMMAND ${GIT_EXECUTABLE} submodule status
-      WORKING_DIRECTORY ${root_path}
-      OUTPUT_VARIABLE submodule_status
-      )
-
-    # git submodule status output not guaranteed to be stable,
-    # may need to check GIT_VERSION_STRING and do some fiddling in the
-    # future...
-
-    lines2list(submodule_status)
-
-    foreach(line ${submodule_status})
-      string(REGEX MATCH "(.)[0-9a-f]+ ([^\( ]+) ?" _ignored "${line}")
-      set(status "${CMAKE_MATCH_1}")
-      set(submodule_path "${CMAKE_MATCH_2}")
-
-      if("${status}" STREQUAL "-")  # missing submodule
-        message(STATUS "Initialising new submodule ${submodule_path}...")
         execute_process(
-          COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive ${submodule_path}
-          WORKING_DIRECTORY ${root_path}
-          RESULT_VARIABLE git_result
-          )
-        if(git_result)
-          message(FATAL_ERROR "Git submodule init failed for ${submodule_path}")
-        endif(git_result)
+            COMMAND ${GIT_EXECUTABLE} submodule status
+            WORKING_DIRECTORY ${root_path}
+            OUTPUT_VARIABLE submodule_status
+            )
 
-      elseif(NOT "${status}" STREQUAL " ")
-        message(WARNING "Git submodule ${submodule_path} is out of date. Run 'git submodule update --init --recursive' to fix.")
-      endif()
+        # git submodule status output not guaranteed to be stable,
+        # may need to check GIT_VERSION_STRING and do some fiddling in the
+        # future...
 
-      # Force a re-run of cmake if the submodule's .git file changes or is changed (ie accidental deinit)
-      get_filename_component(submodule_abs_path ${submodule_path} ABSOLUTE BASE_DIR ${root_path})
-      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_abs_path}/.git)
-      # same if the HEAD file in the submodule's directory changes (ie commit changes). This will at least prit the 'out of date' warning
-      set(submodule_head "${root_path}/.git/modules/${submodule_path}/HEAD")
-      if(EXISTS "${submodule_head}")
-        set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_head})
-      endif()
+        lines2list(submodule_status)
 
-    endforeach()
-  endfunction(git_submodule_check)
+        foreach(line ${submodule_status})
+            string(REGEX MATCH "(.)[0-9a-f]+ ([^\( ]+) ?" _ignored "${line}")
+            set(status "${CMAKE_MATCH_1}")
+            set(submodule_path "${CMAKE_MATCH_2}")
 
-endif(NOT GIT_FOUND)
+            if("${status}" STREQUAL "-")  # missing submodule
+                message(STATUS "Initialising new submodule ${submodule_path}...")
+                execute_process(
+                    COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive ${submodule_path}
+                    WORKING_DIRECTORY ${root_path}
+                    RESULT_VARIABLE git_result
+                    )
+                if(git_result)
+                    message(FATAL_ERROR "Git submodule init failed for ${submodule_path}")
+                endif()
 
+            elseif(NOT "${status}" STREQUAL " ")
+                message(WARNING "Git submodule ${submodule_path} is out of date. "
+                    "Run 'git submodule update --init --recursive' to fix.")
+            endif()
 
+            # Force a re-run of cmake if the submodule's .git file changes or is changed (ie accidental deinit)
+            get_filename_component(submodule_abs_path ${submodule_path} ABSOLUTE BASE_DIR ${root_path})
+            set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_abs_path}/.git)
+            # same if the HEAD file in the submodule's directory changes (ie commit changes).
+            # This will at least print the 'out of date' warning
+            set(submodule_head "${root_path}/.git/modules/${submodule_path}/HEAD")
+            if(EXISTS "${submodule_head}")
+                set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${submodule_head})
+            endif()
 
+        endforeach()
+    endfunction()
 
+endif()
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 2cb406e18..b679b98d3 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -9,27 +9,27 @@ include(crosstool_version_check)
 # loaded and the toolchain and project are not yet set
 #
 macro(idf_set_global_variables)
-  # Note that CONFIG_xxx is not available when this function is called
+    # Note that CONFIG_xxx is not available when this function is called
 
-  set_default(EXTRA_COMPONENT_DIRS "")
+    set_default(EXTRA_COMPONENT_DIRS "")
 
-  # PROJECT_PATH has the path to the IDF project (top-level cmake directory)
-  #
-  # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
-  set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
+    # PROJECT_PATH has the path to the IDF project (top-level cmake directory)
+    #
+    # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
+    set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
 
-  # Note: "main" is no longer a component...
-  #
-  set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
-  spaces2list(COMPONENT_DIRS)
+    # Note: "main" is no longer a component...
+    #
+    set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
+    spaces2list(COMPONENT_DIRS)
 
-  spaces2list(COMPONENTS)
+    spaces2list(COMPONENTS)
 
-  # Tell cmake to drop executables in the top-level build dir
-  set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}")
+    # Tell cmake to drop executables in the top-level build dir
+    set(EXECUTABLE_OUTPUT_PATH "${CMAKE_BINARY_DIR}")
 
-  # path to idf.py tool
-  set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
+    # path to idf.py tool
+    set(IDFTOOL ${PYTHON} "${IDF_PATH}/tools/idf.py")
 endmacro()
 
 # Add all the IDF global compiler & preprocessor options
@@ -39,52 +39,63 @@ endmacro()
 # don't call or edit this function. TODO DESCRIBE WHAT TO DO INSTEAD
 #
 function(idf_set_global_compiler_options)
-  add_definitions(-DESP_PLATFORM)
-  add_definitions(-DHAVE_CONFIG_H)
+    add_definitions(-DESP_PLATFORM)
+    add_definitions(-DHAVE_CONFIG_H)
 
-  if(CONFIG_OPTIMIZATION_LEVEL_RELEASE)
-    add_compile_options(-Os)
-  else()
-    add_compile_options(-Og)
-  endif()
-
-  add_c_compile_options(-std=gnu99)
-
-  add_cxx_compile_options(-std=gnu++11 -fno-rtti)
-
-  if(CONFIG_CXX_EXCEPTIONS)
-    add_cxx_compile_options(-fexceptions)
-  else()
-    add_cxx_compile_options(-fno-exceptions)
-  endif()
-
-  # Default compiler configuration
-  add_compile_options(-ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib)
-
-  # Default warnings configuration
-  add_compile_options(-Wall -Werror=all -Wno-error=unused-function -Wno-error=unused-but-set-variable -Wno-error=unused-variable -Wno-error=deprecated-declarations -Wextra -Wno-unused-parameter -Wno-sign-compare)
-  add_c_compile_options(-Wno-old-style-declaration)
-
-  # Stack protection
-  if(NOT BOOTLOADER_BUILD)
-    if(CONFIG_STACK_CHECK_NORM)
-      add_compile_options(-fstack-protector)
-    elseif(CONFIG_STACK_CHECK_STRONG)
-      add_compile_options(-fstack-protector-strong)
-    elseif(CONFIG_STACK_CHECK_ALL)
-      add_compile_options(-fstack-protector-all)
+    if(CONFIG_OPTIMIZATION_LEVEL_RELEASE)
+        add_compile_options(-Os)
+    else()
+        add_compile_options(-Og)
     endif()
-  endif()
 
-  if(CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED)
-    add_definitions(-DNDEBUG)
-  endif()
+    add_c_compile_options(-std=gnu99)
 
-  # Always generate debug symbols (even in Release mode, these don't
-  # go into the final binary so have no impact on size)
-  add_compile_options(-ggdb)
+    add_cxx_compile_options(-std=gnu++11 -fno-rtti)
 
-  add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
+    if(CONFIG_CXX_EXCEPTIONS)
+        add_cxx_compile_options(-fexceptions)
+    else()
+        add_cxx_compile_options(-fno-exceptions)
+    endif()
+
+    # Default compiler configuration
+    add_compile_options(-ffunction-sections -fdata-sections -fstrict-volatile-bitfields -mlongcalls -nostdlib)
+
+    # Default warnings configuration
+    add_compile_options(
+        -Wall
+        -Werror=all
+        -Wno-error=unused-function
+        -Wno-error=unused-but-set-variable
+        -Wno-error=unused-variable
+        -Wno-error=deprecated-declarations
+        -Wextra
+        -Wno-unused-parameter
+        -Wno-sign-compare)
+    add_c_compile_options(
+        -Wno-old-style-declaration
+        )
+
+    # Stack protection
+    if(NOT BOOTLOADER_BUILD)
+        if(CONFIG_STACK_CHECK_NORM)
+            add_compile_options(-fstack-protector)
+        elseif(CONFIG_STACK_CHECK_STRONG)
+            add_compile_options(-fstack-protector-strong)
+        elseif(CONFIG_STACK_CHECK_ALL)
+            add_compile_options(-fstack-protector-all)
+        endif()
+    endif()
+
+    if(CONFIG_OPTIMIZATION_ASSERTIONS_DISABLED)
+        add_definitions(-DNDEBUG)
+    endif()
+
+    # Always generate debug symbols (even in Release mode, these don't
+    # go into the final binary so have no impact on size)
+    add_compile_options(-ggdb)
+
+    add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
     # Enable ccache if it's on the path
     find_program(CCACHE_FOUND ccache)
@@ -93,27 +104,27 @@ function(idf_set_global_compiler_options)
         set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
     endif()
 
-endfunction(idf_set_global_compiler_options)
+endfunction()
 
 
 # Verify the IDF environment is configured correctly (environment, toolchain, etc)
 function(idf_verify_environment)
 
-  if(NOT CMAKE_PROJECT_NAME)
-    message(FATAL_ERROR "Internal error, IDF project.cmake should have set this variable already")
-  endif()
+    if(NOT CMAKE_PROJECT_NAME)
+        message(FATAL_ERROR "Internal error, IDF project.cmake should have set this variable already")
+    endif()
 
-  # Check toolchain is configured properly in cmake
-  if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
-    message(FATAL_ERROR "Internal error, toolchain has not been set correctly by project")
-  endif()
+    # Check toolchain is configured properly in cmake
+    if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
+        message(FATAL_ERROR "Internal error, toolchain has not been set correctly by project")
+    endif()
 
-  #
-  # Warn if the toolchain version doesn't match
-  #
-  # TODO: make these platform-specific for diff toolchains
-  gcc_version_check("5.2.0")
-  crosstool_version_check("1.22.0-80-g6c4433a")
+    #
+    # Warn if the toolchain version doesn't match
+    #
+    # TODO: make these platform-specific for diff toolchains
+    gcc_version_check("5.2.0")
+    crosstool_version_check("1.22.0-80-g6c4433a")
 
 endfunction()
 
@@ -123,62 +134,54 @@ endfunction()
 # Adds .map & .bin file targets
 # Sets up flash-related targets
 function(idf_add_executable)
-  set(exe_target ${PROJECT_NAME}.elf)
- 
-  spaces2list(MAIN_SRCS)
-  add_executable(${exe_target} "${MAIN_SRCS}")
+    set(exe_target ${PROJECT_NAME}.elf)
 
-  add_map_file(${exe_target})
+    spaces2list(MAIN_SRCS)
+    add_executable(${exe_target} "${MAIN_SRCS}")
 
-  add_flasher_argfile(${exe_target})
-
-endfunction(idf_add_executable)
+    add_map_file(${exe_target})
+endfunction()
 
 
 # add_map_file
 #
 # Set linker args for 'exe_target' to generate a linker Map file
 function(add_map_file exe_target)
-  get_filename_component(basename ${exe_target} NAME_WE)
-  set(mapfile "${basename}.map")
-  target_link_libraries(${exe_target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
-  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
+    get_filename_component(basename ${exe_target} NAME_WE)
+    set(mapfile "${basename}.map")
+    target_link_libraries(${exe_target} "-Wl,--gc-sections -Wl,--cref -Wl,--Map=${mapfile} -Wl,--start-group")
+    set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY
+        ADDITIONAL_MAKE_CLEAN_FILES
+        "${CMAKE_CURRENT_BINARY_DIR}/${mapfile}")
 
-  # add size targets, depend on map file, run idf_size.py
-  add_custom_target(size
-    DEPENDS ${exe_target}
-    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py ${mapfile}
-    )
-  add_custom_target(size-files
-    DEPENDS ${exe_target}
-    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --files ${mapfile}
-    )
-  add_custom_target(size-components
-    DEPENDS ${exe_target}
-    COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --archives ${mapfile}
-    )
+    # add size targets, depend on map file, run idf_size.py
+    add_custom_target(size
+        DEPENDS ${exe_target}
+        COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py ${mapfile}
+        )
+    add_custom_target(size-files
+        DEPENDS ${exe_target}
+        COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --files ${mapfile}
+        )
+    add_custom_target(size-components
+        DEPENDS ${exe_target}
+        COMMAND ${PYTHON} ${IDF_PATH}/tools/idf_size.py --archives ${mapfile}
+        )
 
-endfunction(add_map_file)
-
-# add_flasher_argfile
-#
-# Add argument file(s) for flashing the app, and for flashing the whole system
-function(add_flasher_argfile)
-
-endfunction(add_flasher_argfile)
+endfunction()
 
 # component_compile_options
 #
 # Wrapper around target_compile_options that passes the component name
 function(component_compile_options)
-  target_compile_options(${COMPONENT_NAME} PRIVATE ${ARGV})
+    target_compile_options(${COMPONENT_NAME} PRIVATE ${ARGV})
 endfunction()
 
 # component_compile_definitions
 #
 # Wrapper around target_compile_definitions that passes the component name
 function(component_compile_definitions)
-  target_compile_definitions(${COMPONENT_NAME} PRIVATE ${ARGV})
+    target_compile_definitions(${COMPONENT_NAME} PRIVATE ${ARGV})
 endfunction()
 
 # idf_get_git_revision
@@ -188,8 +191,8 @@ endfunction()
 # Running git_describe() here automatically triggers rebuilds
 # if the ESP-IDF git version changes
 function(idf_get_git_revision)
-  git_describe(IDF_VER "${IDF_PATH}")
-  add_definitions(-DIDF_VER=\"${IDF_VER}\")
-  git_submodule_check("${IDF_PATH}")
-  set(IDF_VER ${IDF_VER} PARENT_SCOPE)
+    git_describe(IDF_VER "${IDF_PATH}")
+    add_definitions(-DIDF_VER=\"${IDF_VER}\")
+    git_submodule_check("${IDF_PATH}")
+    set(IDF_VER ${IDF_VER} PARENT_SCOPE)
 endfunction()
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index c2d809995..277568959 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -1,103 +1,106 @@
 include(ExternalProject)
 
 macro(kconfig_set_variables)
-  set(MCONF kconfig_bin/mconf)
+    set(MCONF kconfig_bin/mconf)
 
-  set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
-  set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
-  set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
-  set(SDKCONFIG_JSON ${CMAKE_BINARY_DIR}/sdkconfig.json)
+    set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
+    set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
+    set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
+    set(SDKCONFIG_JSON ${CMAKE_BINARY_DIR}/sdkconfig.json)
 
-  set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
+    set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
 
-  set_default(SDKCONFIG_DEFAULTS "${SDKCONFIG}.defaults")
+    set_default(SDKCONFIG_DEFAULTS "${SDKCONFIG}.defaults")
 endmacro()
 
 # Use the existing Makefile to build mconf (out of tree) when needed
 #
 # TODO: Download(?) a prebuilt mingw mconf on Windows
-ExternalProject_Add(mconf
-  SOURCE_DIR ${IDF_PATH}/tools/kconfig
-  CONFIGURE_COMMAND ""
-  BINARY_DIR "kconfig_bin"
-  BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
-  BUILD_BYPRODUCTS ${MCONF}
-  INSTALL_COMMAND ""
-  EXCLUDE_FROM_ALL 1
-  )
+externalproject_add(mconf
+    SOURCE_DIR ${IDF_PATH}/tools/kconfig
+    CONFIGURE_COMMAND ""
+    BINARY_DIR "kconfig_bin"
+    BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
+    BUILD_BYPRODUCTS ${MCONF}
+    INSTALL_COMMAND ""
+    EXCLUDE_FROM_ALL 1
+    )
 
 
 # Find all Kconfig files for all components
 function(kconfig_process_config)
-  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
-  set(kconfigs )
-  set(kconfigs_projbuild )
+    file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
+    set(kconfigs)
+    set(kconfigs_projbuild)
 
-  # Find Kconfig and Kconfig.projbuild for each component as applicable
-  # if any of these change, cmake should rerun
-  foreach(dir ${COMPONENT_PATHS} "${CMAKE_SOURCE_DIR}/main")
-    file(GLOB kconfig "${dir}/Kconfig")
-    if(kconfig)
-      set(kconfigs "${kconfigs} ${kconfig}")
-      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+    # Find Kconfig and Kconfig.projbuild for each component as applicable
+    # if any of these change, cmake should rerun
+    foreach(dir ${COMPONENT_PATHS} "${CMAKE_SOURCE_DIR}/main")
+        file(GLOB kconfig "${dir}/Kconfig")
+        if(kconfig)
+            set(kconfigs "${kconfigs} ${kconfig}")
+            set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+        endif()
+        file(GLOB kconfig ${dir}/Kconfig.projbuild)
+        if(kconfig)
+            set(kconfigs_projbuild "${kconfigs_projbuild} ${kconfig}")
+            set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+        endif()
+    endforeach()
+
+    if(EXISTS ${SDKCONFIG_DEFAULTS})
+        set(defaults_arg --defaults "${SDKCONFIG_DEFAULTS}")
     endif()
-    file(GLOB kconfig ${dir}/Kconfig.projbuild)
-    if(kconfig)
-      set(kconfigs_projbuild "${kconfigs_projbuild} ${kconfig}")
-      set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${kconfig})
+
+    set(confgen_basecommand
+        ${PYTHON} ${IDF_PATH}/tools/kconfig_new/confgen.py
+        --kconfig ${ROOT_KCONFIG}
+        --config ${SDKCONFIG}
+        ${defaults_arg}
+        --create-config-if-missing
+        --env "COMPONENT_KCONFIGS=${kconfigs}"
+        --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}")
+
+    # Generate the menuconfig target (uses C-based mconf tool)
+    add_custom_target(menuconfig
+        DEPENDS mconf
+        # create any missing config file, with defaults if necessary
+        COMMAND ${confgen_basecommand} --output config ${SDKCONFIG}
+        COMMAND ${CMAKE_COMMAND} -E env
+        "COMPONENT_KCONFIGS=${kconfigs}"
+        "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+        "KCONFIG_CONFIG=${SDKCONFIG}"
+        ${MCONF} ${ROOT_KCONFIG}
+        VERBATIM
+        USES_TERMINAL)
+
+    # Generate configuration output via confgen.py
+    # makes sdkconfig.h and skdconfig.cmake
+    #
+    # This happens during the cmake run not during the build
+    execute_process(COMMAND ${confgen_basecommand}
+        --output header ${SDKCONFIG_HEADER}
+        --output cmake ${SDKCONFIG_CMAKE}
+        --output json ${SDKCONFIG_JSON}
+        RESULT_VARIABLE config_result)
+    if(config_result)
+        message(FATAL_ERROR "Failed to run confgen.py (${confgen_basecommand}). Error ${config_result}")
     endif()
-  endforeach(dir ${COMPONENT_PATHS})
 
-  if(EXISTS ${SDKCONFIG_DEFAULTS})
-    set(defaults_arg --defaults "${SDKCONFIG_DEFAULTS}")
-  endif()
+    # When sdkconfig file changes in the future, trigger a cmake run
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG}")
 
-  set(confgen_basecommand
-    ${PYTHON} ${IDF_PATH}/tools/kconfig_new/confgen.py
-    --kconfig ${ROOT_KCONFIG}
-    --config ${SDKCONFIG}
-    ${defaults_arg}
-    --create-config-if-missing
-    --env "COMPONENT_KCONFIGS=${kconfigs}"
-    --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}")
+    # Ditto if either of the generated files are missing/modified (this is a bit irritating as it means
+    # you can't edit these manually without them being regenerated, but I don't know of a better way...)
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_HEADER}")
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_CMAKE}")
 
-  # Generate the menuconfig target (uses C-based mconf tool)
-  add_custom_target(menuconfig
-    DEPENDS mconf
-    COMMAND ${confgen_basecommand} --output config ${SDKCONFIG}  # create any missing config file, with defaults if necessary
-    COMMAND ${CMAKE_COMMAND} -E env
-                "COMPONENT_KCONFIGS=${kconfigs}"
-                "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
-                "KCONFIG_CONFIG=${SDKCONFIG}"
-                ${MCONF} ${ROOT_KCONFIG}
-    VERBATIM
-    USES_TERMINAL)
+    # Or if the config generation tool changes
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/confgen.py")
+    set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/kconfiglib.py")
 
-  # Generate configuration output via confgen.py
-  # makes sdkconfig.h and skdconfig.cmake
-  #
-  # This happens during the cmake run not during the build
-  execute_process(COMMAND ${confgen_basecommand}
-    --output header ${SDKCONFIG_HEADER}
-    --output cmake ${SDKCONFIG_CMAKE}
-    --output json ${SDKCONFIG_JSON}
-	RESULT_VARIABLE config_result)
-  if(config_result)
-	message(FATAL_ERROR "Failed to run confgen.py (${confgen_basecommand}). Error ${config_result}")
-  endif()
-
-  # When sdkconfig file changes in the future, trigger a cmake run
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG}")
-
-  # Ditto if either of the generated files are missing/modified (this is a bit irritating as it means
-  # you can't edit these manually without them being regenerated, but I don't know of a better way...)
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_HEADER}")
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${SDKCONFIG_CMAKE}")
-
-  # Or if the config generation tool changes
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/confgen.py")
-  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS "${IDF_PATH}/tools/kconfig_new/kconfiglib.py")
-
-  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${SDKCONFIG_HEADER}" "${SDKCONFIG_CMAKE}")
+    set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY
+        ADDITIONAL_MAKE_CLEAN_FILES
+        "${SDKCONFIG_HEADER}" "${SDKCONFIG_CMAKE}")
 
 endfunction()
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 0072c9372..ef5f6740d 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -5,16 +5,19 @@ cmake_minimum_required(VERSION 3.5)
 # Set IDF_PATH, as nothing else will work without this
 set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
-  # Documentation says you should set IDF_PATH in your environment, but we
-  # can infer it here if it's not set.
-  set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
-  set($ENV{IDF_PATH} "${IDF_PATH}")
+    # Documentation says you should set IDF_PATH in your environment, but we
+    # can infer it here if it's not set.
+    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
+    set($ENV{IDF_PATH} "${IDF_PATH}")
 endif()
 
 #
 # Load cmake modules
 #
-set(CMAKE_MODULE_PATH "${IDF_PATH}/tools/cmake" "${IDF_PATH}/tools/cmake/third_party" ${CMAKE_MODULE_PATH})
+set(CMAKE_MODULE_PATH
+    "${IDF_PATH}/tools/cmake"
+    "${IDF_PATH}/tools/cmake/third_party"
+    ${CMAKE_MODULE_PATH})
 include(GetGitRevisionDescription)
 include(utilities)
 include(components)
@@ -29,85 +32,88 @@ set_default(PYTHON "python")
 # This macro wraps the cmake 'project' command to add
 # all of the IDF-specific functionality required
 #
-# Implementation Note: This macro wraps 'project' on purpose, because cmake has some
-# backwards-compatible magic where if you don't call "project" in the top-level
-# CMakeLists file, it will call it implicitly. However, the implict project will not
-# have CMAKE_TOOLCHAIN_FILE set and therefore tries to create a native build project.
+# Implementation Note: This macro wraps 'project' on purpose, because cmake has
+# some backwards-compatible magic where if you don't call "project" in the
+# top-level CMakeLists file, it will call it implicitly. However, the implicit
+# project will not have CMAKE_TOOLCHAIN_FILE set and therefore tries to
+# create a native build project.
 #
 # Therefore, to keep all the IDF "build magic", the cleanest way is to keep the
-# top-level "project" call but customize it to do what we want in the IDF build...
+# top-level "project" call but customize it to do what we want in the IDF build.
 #
 macro(project name)
-  # Set global variables used by rest of the build
-  idf_set_global_variables()
+    # Set global variables used by rest of the build
+    idf_set_global_variables()
 
-  # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each component in COMPONENT_PATHS
-  components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}" COMPONENT_PATHS COMPONENTS)
+    # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each
+    # component in COMPONENT_PATHS
+    components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}"
+        COMPONENT_PATHS COMPONENTS)
 
-  # Print list of components
-  string(REPLACE ";" " " COMPONENTS_SPACES "${COMPONENTS}")
-  message(STATUS "Component names: ${COMPONENTS_SPACES}")
-  unset(COMPONENTS_SPACES)
-  message(STATUS "Component paths: ${COMPONENT_PATHS}")
+    # Print list of components
+    string(REPLACE ";" " " COMPONENTS_SPACES "${COMPONENTS}")
+    message(STATUS "Component names: ${COMPONENTS_SPACES}")
+    unset(COMPONENTS_SPACES)
+    message(STATUS "Component paths: ${COMPONENT_PATHS}")
 
-  kconfig_set_variables()
+    kconfig_set_variables()
 
-  kconfig_process_config()
+    kconfig_process_config()
 
-  # Include sdkconfig.cmake so rest of the build knows the configuration
-  include(${SDKCONFIG_CMAKE})
+    # Include sdkconfig.cmake so rest of the build knows the configuration
+    include(${SDKCONFIG_CMAKE})
 
-  # Now the configuration is loaded, set the toolchain appropriately
-  #
-  # TODO: support more toolchains than just ESP32
-  set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/tools/cmake/toolchain-esp32.cmake)
+    # Now the configuration is loaded, set the toolchain appropriately
+    #
+    # TODO: support more toolchains than just ESP32
+    set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/tools/cmake/toolchain-esp32.cmake)
 
-  # Declare the actual cmake-level project
-  _project(${name} ASM C CXX)
+    # Declare the actual cmake-level project
+    _project(${name} ASM C CXX)
 
-  # generate compile_commands.json (needs to come after project)
-  set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
+    # generate compile_commands.json (needs to come after project)
+    set(CMAKE_EXPORT_COMPILE_COMMANDS 1)
 
-   # Verify the environment is configured correctly
-  idf_verify_environment()
+    # Verify the environment is configured correctly
+    idf_verify_environment()
 
-  # Add some idf-wide definitions
-  idf_set_global_compiler_options()
+    # Add some idf-wide definitions
+    idf_set_global_compiler_options()
 
-  # Check git revision (may trigger reruns of cmake)
-  ##  sets IDF_VER to IDF git revision
-  idf_get_git_revision()
-  ## if project uses git, retrieve revision
-  git_describe(PROJECT_VER "${CMAKE_CURRENT_SOURCE_DIR}")
+    # Check git revision (may trigger reruns of cmake)
+    ##  sets IDF_VER to IDF git revision
+    idf_get_git_revision()
+    ## if project uses git, retrieve revision
+    git_describe(PROJECT_VER "${CMAKE_CURRENT_SOURCE_DIR}")
 
-  # Include any top-level project_include.cmake files from components
-  foreach(component ${COMPONENT_PATHS})
-    include_if_exists("${component}/project_include.cmake")
-  endforeach()
+    # Include any top-level project_include.cmake files from components
+    foreach(component ${COMPONENT_PATHS})
+        include_if_exists("${component}/project_include.cmake")
+    endforeach()
 
-  #
-  # Add each component to the build as a library
-  #
-  foreach(COMPONENT_PATH ${COMPONENT_PATHS})
-    get_filename_component(COMPONENT_NAME ${COMPONENT_PATH} NAME)
-    add_subdirectory(${COMPONENT_PATH} ${COMPONENT_NAME})
-  endforeach()
-  unset(COMPONENT_NAME)
-  unset(COMPONENT_PATH)
+    #
+    # Add each component to the build as a library
+    #
+    foreach(COMPONENT_PATH ${COMPONENT_PATHS})
+        get_filename_component(COMPONENT_NAME ${COMPONENT_PATH} NAME)
+        add_subdirectory(${COMPONENT_PATH} ${COMPONENT_NAME})
+    endforeach()
+    unset(COMPONENT_NAME)
+    unset(COMPONENT_PATH)
 
-  #
-  # Add the app executable to the build (has name of PROJECT.elf)
-  #
-  idf_add_executable()
+    #
+    # Add the app executable to the build (has name of PROJECT.elf)
+    #
+    idf_add_executable()
 
-  # Write project description JSON file
-  configure_file("${IDF_PATH}/tools/cmake/project_description.json.in"
-    "${CMAKE_BINARY_DIR}/project_description.json")
+    # Write project description JSON file
+    configure_file("${IDF_PATH}/tools/cmake/project_description.json.in"
+        "${CMAKE_BINARY_DIR}/project_description.json")
 
-  #
-  # Finish component registration (add cross-dependencies, make
-  # executable dependent on all components)
-  #
-  components_finish_registration()
+    #
+    # Finish component registration (add cross-dependencies, make
+    # executable dependent on all components)
+    #
+    components_finish_registration()
 
-endmacro(project)
+endmacro()
diff --git a/tools/cmake/run_cmake_lint.sh b/tools/cmake/run_cmake_lint.sh
new file mode 100755
index 000000000..65f49eed2
--- /dev/null
+++ b/tools/cmake/run_cmake_lint.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+#
+# Run cmakelint on all cmake files in IDF_PATH (except third party)
+#
+# cmakelint: https://github.com/richq/cmake-lint
+#
+# NOTE: This script makes use of features in (currently unreleased)
+# cmakelint >1.4. Install directly from github as follows:
+#
+# pip install https://github.com/richq/cmake-lint/archive/058c6c0ed2536.zip
+#
+
+if [ -z "${IDF_PATH}" ]; then
+    echo "IDF_PATH variable needs to be set"
+    exit 3
+fi
+
+# exclusions include some third-party directories which contain upstream
+# CMakeLists files
+find ${IDF_PATH} \
+     -name build -prune \
+     -o -name third_party -prune \
+     \
+     -o -name 'nghttp2' -prune \
+     -o -name 'cJSON' -prune \
+     -o -name 'Findsodium.cmake' -prune \
+     \
+     -o -name CMakeLists.txt -print0 \
+     -o -name '*.cmake' -print0 \
+    | xargs -0 cmakelint --linelength=120 --spaces=4
+
+
diff --git a/tools/cmake/scripts/data_file_to_c.cmake b/tools/cmake/scripts/data_file_to_c.cmake
index 6d20eca7e..fb93bfddc 100644
--- a/tools/cmake/scripts/data_file_to_c.cmake
+++ b/tools/cmake/scripts/data_file_to_c.cmake
@@ -16,17 +16,17 @@
 #
 #
 if(NOT DATA_FILE)
-  message(FATAL_ERROR "DATA_FILE for converting must be specified")
+    message(FATAL_ERROR "DATA_FILE for converting must be specified")
 endif()
 
 if(NOT SOURCE_FILE)
-  message(FATAL_ERROR "SOURCE_FILE destination must be specified")
+    message(FATAL_ERROR "SOURCE_FILE destination must be specified")
 endif()
 
 file(READ "${DATA_FILE}" data HEX)
 
 if(FILE_TYPE STREQUAL "TEXT")
-  set(data "${data}00")  # null-byte terimnation
+    set(data "${data}00")  # null-byte terimnation
 endif()
 
 ## Convert string of raw hex bytes to lines of hex bytes in C array format
@@ -41,7 +41,7 @@ string(MAKE_C_IDENTIFIER "${source_filename}" varname)
 file(WRITE "${SOURCE_FILE}"  "/*\n")
 file(APPEND "${SOURCE_FILE}" " * Data converted from ${DATA_FILE}\n")
 if(FILE_TYPE STREQUAL "TEXT")
-  file(APPEND "${SOURCE_FILE}" " * (null byte appended)\n")
+    file(APPEND "${SOURCE_FILE}" " * (null byte appended)\n")
 endif()
 file(APPEND "${SOURCE_FILE}" " */\n")
 file(APPEND "${SOURCE_FILE}" "#include <stdlib.h>\n")
diff --git a/tools/cmake/toolchain-esp32.cmake b/tools/cmake/toolchain-esp32.cmake
index cecba78af..c23fa4cbc 100644
--- a/tools/cmake/toolchain-esp32.cmake
+++ b/tools/cmake/toolchain-esp32.cmake
@@ -1,7 +1,7 @@
-set(CMAKE_SYSTEM_NAME Generic)
-
-set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
-set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
-set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
-
-set(CMAKE_EXE_LINKER_FLAGS "-nostdlib" CACHE STRING "Linker Base Flags")
+set(CMAKE_SYSTEM_NAME Generic)
+
+set(CMAKE_C_COMPILER xtensa-esp32-elf-gcc)
+set(CMAKE_CXX_COMPILER xtensa-esp32-elf-g++)
+set(CMAKE_ASM_COMPILER xtensa-esp32-elf-gcc)
+
+set(CMAKE_EXE_LINKER_FLAGS "-nostdlib" CACHE STRING "Linker Base Flags")
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 759b559a3..0415e6497 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -8,13 +8,13 @@
 # - Default value as provided to function
 #
 function(set_default variable default_value)
-  if(NOT ${variable})
-    if($ENV{${variable}})
-      set(${variable} $ENV{${variable}} PARENT_SCOPE)
-    else()
-      set(${variable} ${default_value} PARENT_SCOPE)
+    if(NOT ${variable})
+        if($ENV{${variable}})
+            set(${variable} $ENV{${variable}} PARENT_SCOPE)
+        else()
+            set(${variable} ${default_value} PARENT_SCOPE)
+        endif()
     endif()
-  endif()
 endfunction()
 
 # spaces2list
@@ -27,8 +27,8 @@ endfunction()
 #
 # TODO: look at cmake separate_arguments, which is quote-aware
 function(spaces2list variable_name)
-  string(REPLACE " " ";" tmp "${${variable_name}}")
-  set("${variable_name}" "${tmp}" PARENT_SCOPE)
+    string(REPLACE " " ";" tmp "${${variable_name}}")
+    set("${variable_name}" "${tmp}" PARENT_SCOPE)
 endfunction()
 
 
@@ -38,9 +38,9 @@ endfunction()
 # to a cmake list (semicolon-delimited), one line per item
 #
 function(lines2list variable_name)
-  string(REGEX REPLACE "\r?\n" ";" tmp "${${variable_name}}")
-  string(REGEX REPLACE ";;" ";" tmp "${tmp}")
-  set("${variable_name}" "${tmp}" PARENT_SCOPE)
+    string(REGEX REPLACE "\r?\n" ";" tmp "${${variable_name}}")
+    string(REGEX REPLACE ";;" ";" tmp "${tmp}")
+    set("${variable_name}" "${tmp}" PARENT_SCOPE)
 endfunction()
 
 
@@ -54,23 +54,23 @@ endfunction()
 # Avoids timestamp updates for re-generated files where content hasn't
 # changed.
 function(move_if_different source destination)
-  set(do_copy 1)
-  file(GLOB dest_exists ${destination})
-  if(dest_exists)
-    file(MD5 ${source} source_md5)
-    file(MD5 ${destination} dest_md5)
-    if(source_md5 STREQUAL dest_md5)
-      set(do_copy "")
+    set(do_copy 1)
+    file(GLOB dest_exists ${destination})
+    if(dest_exists)
+        file(MD5 ${source} source_md5)
+        file(MD5 ${destination} dest_md5)
+        if(source_md5 STREQUAL dest_md5)
+            set(do_copy "")
+        endif()
     endif()
-  endif()
 
-  if(do_copy)
-    message("Moving ${source} -> ${destination}")
-    file(RENAME ${source} ${destination})
-  else()
-    message("Not moving ${source} -> ${destination}")
-    file(REMOVE ${source})
-  endif()
+    if(do_copy)
+        message("Moving ${source} -> ${destination}")
+        file(RENAME ${source} ${destination})
+    else()
+        message("Not moving ${source} -> ${destination}")
+        file(REMOVE ${source})
+    endif()
 
 endfunction()
 
@@ -80,10 +80,10 @@ endfunction()
 # This adds global options, set target properties for
 # component-specific flags
 function(add_cxx_compile_options)
-  foreach(option ${ARGV})
-    # note: the Visual Studio Generator doesn't support this...
-    add_compile_options($<$<COMPILE_LANGUAGE:CXX>:${option}>)
-  endforeach()
+    foreach(option ${ARGV})
+        # note: the Visual Studio Generator doesn't support this...
+        add_compile_options($<$<COMPILE_LANGUAGE:CXX>:${option}>)
+    endforeach()
 endfunction()
 
 # add_compile_options variant for C code only
@@ -91,10 +91,10 @@ endfunction()
 # This adds global options, set target properties for
 # component-specific flags
 function(add_c_compile_options)
-  foreach(option ${ARGV})
-    # note: the Visual Studio Generator doesn't support this...
-    add_compile_options($<$<COMPILE_LANGUAGE:C>:${option}>)
-  endforeach()
+    foreach(option ${ARGV})
+        # note: the Visual Studio Generator doesn't support this...
+        add_compile_options($<$<COMPILE_LANGUAGE:C>:${option}>)
+    endforeach()
 endfunction()
 
 
@@ -103,46 +103,45 @@ endfunction()
 # to a binary object as part of the build
 function(target_add_binary_data target embed_file embed_type)
 
-  get_filename_component(embed_file "${embed_file}" ABSOLUTE)
+    get_filename_component(embed_file "${embed_file}" ABSOLUTE)
 
-  get_filename_component(name "${embed_file}" NAME)
-  set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.c")
+    get_filename_component(name "${embed_file}" NAME)
+    set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.c")
 
-  add_custom_command(OUTPUT "${embed_srcfile}"
-    COMMAND "${CMAKE_COMMAND}"
-    -D "DATA_FILE=${embed_file}"
-    -D "SOURCE_FILE=${embed_srcfile}"
-    -D "FILE_TYPE=${embed_type}"
-    -P "${IDF_PATH}/tools/cmake/scripts/data_file_to_c.cmake"
-    MAIN_DEPENDENCY "${embed_file}"
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}")
+    add_custom_command(OUTPUT "${embed_srcfile}"
+        COMMAND "${CMAKE_COMMAND}"
+        -D "DATA_FILE=${embed_file}"
+        -D "SOURCE_FILE=${embed_srcfile}"
+        -D "FILE_TYPE=${embed_type}"
+        -P "${IDF_PATH}/tools/cmake/scripts/data_file_to_c.cmake"
+        MAIN_DEPENDENCY "${embed_file}"
+        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}")
 
-  set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${embed_srcfile}")
+    set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${embed_srcfile}")
 
-  target_sources("${target}" PRIVATE "${embed_srcfile}")
+    target_sources("${target}" PRIVATE "${embed_srcfile}")
 endfunction()
 
 macro(include_if_exists path)
-  if(EXISTS "${path}")
-    include("${path}")
-  endif()
-endmacro(include_if_exists)
+    if(EXISTS "${path}")
+        include("${path}")
+    endif()
+endmacro()
 
 # Append a single line to the file specified
 # The line ending is determined by the host OS
 function(file_append_line file line)
-  if(ENV{MSYSTEM} OR CMAKE_HOST_WIN32)
-    set(line_ending "\r\n")
-  else() # unix
-    set(line_ending "\n")
-  endif()
-  file(READ ${file} existing)
-  string(FIND ${existing} ${line_ending} last_newline REVERSE)
-  string(LENGTH ${existing} length)
-  math(EXPR length "${length}-1")
-  if(NOT length EQUAL last_newline) # file doesn't end with a newline
-    file(APPEND "${file}" "${line_ending}")
-  endif()
-  file(APPEND "${file}" "${line}${line_ending}")
+    if(ENV{MSYSTEM} OR CMAKE_HOST_WIN32)
+        set(line_ending "\r\n")
+    else() # unix
+        set(line_ending "\n")
+    endif()
+    file(READ ${file} existing)
+    string(FIND ${existing} ${line_ending} last_newline REVERSE)
+    string(LENGTH ${existing} length)
+    math(EXPR length "${length}-1")
+    if(NOT length EQUAL last_newline) # file doesn't end with a newline
+        file(APPEND "${file}" "${line_ending}")
+    endif()
+    file(APPEND "${file}" "${line}${line_ending}")
 endfunction()
-

From bc1693aae3af2d7630a26d3d7a95e477f51b70b1 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 16:03:32 +1100
Subject: [PATCH 031/112] cmake: Fix SPIRAM options

---
 components/esp32/CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 31b6ce546..77d4fd0b4 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -31,7 +31,7 @@ else()
     target_link_libraries(esp32 "-T esp32.peripherals.ld")
 
     if(CONFIG_SPIRAM_CACHE_WORKAROUND)
-        target_link_libraries(esp32 ${CMAKE_CURRENT_SOURCE_DIR}/libstdc++-psram-workaround.a)
+        add_compile_options(-mfix-esp32-psram-cache-issue)
     else()
         target_link_libraries(esp32 "-T esp32.rom.spiram_incompatible_fns.ld")
     endif()

From 12be3997623eacb7cc33778e5e1a13c6a898ae87 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 1 Mar 2018 17:02:08 +1100
Subject: [PATCH 032/112] cmake: Add link-time dependencies for linker script
 files

Requires some hackery around limitations in CMake's LINK_DEPENDS
---
 .../bootloader/subproject/CMakeLists.txt      |  5 ++--
 components/esp32/CMakeLists.txt               | 16 ++++++-------
 tools/cmake/components.cmake                  | 18 ++++++++++++++
 tools/cmake/utilities.cmake                   | 24 +++++++++++++++++++
 4 files changed, 52 insertions(+), 11 deletions(-)

diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index 9d99e6e0c..5ac887a40 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -14,8 +14,7 @@ set(MAIN_SRCS main/bootloader_start.c)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(bootloader)
 
-target_link_libraries(bootloader.elf "-L ${CMAKE_CURRENT_SOURCE_DIR}/main")
-target_link_libraries(bootloader.elf "-T esp32.bootloader.ld")
-target_link_libraries(bootloader.elf "-T esp32.bootloader.rom.ld")
+target_linker_script(bootloader.elf "main/esp32.bootloader.ld")
+target_linker_script(bootloader.elf "main/esp32.bootloader.rom.ld")
 target_link_libraries(bootloader.elf "${BOOTLOADER_LINKER_ARGS}")
 target_link_libraries(bootloader.elf gcc)
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 77d4fd0b4..1172dda7f 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -24,24 +24,24 @@ else()
     if(NOT CONFIG_NO_BLOBS)
         target_link_libraries(esp32 coexist core espnow net80211 phy pp rtc smartconfig wpa2 wpa wps)
     endif()
-    target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld")
-    target_link_libraries(esp32 "-T ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
-    target_link_libraries(esp32 "-T esp32.common.ld")
-    target_link_libraries(esp32 "-T esp32.rom.ld")
-    target_link_libraries(esp32 "-T esp32.peripherals.ld")
+    target_linker_script(esp32 "${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
+
+    target_linker_script(esp32 "ld/esp32.common.ld")
+    target_linker_script(esp32 "ld/esp32.rom.ld")
+    target_linker_script(esp32 "ld/esp32.peripherals.ld")
 
     if(CONFIG_SPIRAM_CACHE_WORKAROUND)
         add_compile_options(-mfix-esp32-psram-cache-issue)
     else()
-        target_link_libraries(esp32 "-T esp32.rom.spiram_incompatible_fns.ld")
+        target_linker_script(esp32 "ld/esp32.rom.spiram_incompatible_fns.ld")
     endif()
 
     if(CONFIG_NEWLIB_NANO_FORMAT)
-        target_link_libraries(esp32 "-T esp32.rom.nanofmt.ld")
+        target_linker_script(esp32 "ld/esp32.rom.nanofmt.ld")
     endif()
 
     if(NOT CONFIG_SPI_FLASH_ROM_DRIVER_PATCH)
-        target_link_libraries(esp32 "-T esp32.rom.spiflash.ld")
+        target_linker_script(esp32 "ld/esp32.rom.spiflash.ld")
     endif()
 
     target_link_libraries(esp32 "${CMAKE_CURRENT_SOURCE_DIR}/libhal.a")
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 8c6518703..4334ffee7 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -161,6 +161,24 @@ function(components_finish_registration)
         endif()
     endforeach()
 
+    # Add each component library's link-time dependencies (which are otherwise ignored) to the executable
+    # LINK_DEPENDS in order to trigger a re-link when needed (on Ninja/Makefile generators at least).
+    # (maybe this should probably be something CMake does, but it doesn't do it...)
+    foreach(component ${COMPONENTS})
+        if(TARGET ${component})
+            get_target_property(imported ${component} IMPORTED)
+            get_target_property(type ${component} TYPE)
+            if(NOT imported)
+                if(${type} STREQUAL STATIC_LIBRARY OR ${type} STREQUAL EXECUTABLE)
+                    get_target_property(link_depends "${component}" LINK_DEPENDS)
+                    if(link_depends)
+                        set_property(TARGET ${CMAKE_PROJECT_NAME}.elf APPEND PROPERTY LINK_DEPENDS "${link_depends}")
+                    endif()
+                endif()
+            endif()
+        endif()
+    endforeach()
+
     # Embedded binary & text files
     spaces2list(COMPONENT_EMBED_FILES)
     foreach(embed_src ${COMPONENT_EMBED_FILES})
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 0415e6497..ec6323d90 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -145,3 +145,27 @@ function(file_append_line file line)
     endif()
     file(APPEND "${file}" "${line}${line_ending}")
 endfunction()
+
+# Add a linker script to the target, including a link-time dependency
+#
+# Automatically adds a -L search path for the containing directory (if found),
+# and then adds -T with the filename only. This allows INCLUDE directives to be
+# used to include other linker scripts in the same directory.
+function(target_linker_script target scriptfile)
+    get_filename_component(abs_script "${scriptfile}" ABSOLUTE)
+
+    get_filename_component(search_dir "${abs_script}" DIRECTORY)
+    get_filename_component(scriptname "${abs_script}" NAME)
+
+    get_target_property(link_libraries "${target}" LINK_LIBRARIES)
+    list(FIND "${link_libraries}" "-L ${search_dir}" found_search_dir)
+    if(found_search_dir EQUAL "-1")  # not already added as a search path
+        target_link_libraries("${target}" "-L ${search_dir}")
+    endif()
+
+    target_link_libraries("${target}" "-T ${scriptname}")
+
+    # Note: In ESP-IDF, most targets are libraries and libary LINK_DEPENDS don't propagate to
+    # executable(s) the library is linked to. This is done manually in components.cmake.
+    set_property(TARGET "${target}" APPEND PROPERTY LINK_DEPENDS "${abs_script}")
+endfunction()

From b57843b66aa15033f143c40f54c73440f21d8735 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 1 Mar 2018 17:02:32 +1100
Subject: [PATCH 033/112] cmake: Linker scripts need to account for .c.obj
 extension as well as .o

---
 components/esp32/ld/esp32.common.ld | 38 ++++++++++++++---------------
 1 file changed, 19 insertions(+), 19 deletions(-)

diff --git a/components/esp32/ld/esp32.common.ld b/components/esp32/ld/esp32.common.ld
index c6a92356c..73f592ef1 100644
--- a/components/esp32/ld/esp32.common.ld
+++ b/components/esp32/ld/esp32.common.ld
@@ -10,7 +10,7 @@ SECTIONS
   {
     . = ALIGN(4);
     *(.rtc.literal .rtc.text)
-    *rtc_wake_stub*.o(.literal .text .literal.* .text.*)
+    *rtc_wake_stub*.*(.literal .text .literal.* .text.*)
   } >rtc_iram_seg
 
   /* RTC slow memory holds RTC wake stub
@@ -22,7 +22,7 @@ SECTIONS
     _rtc_data_start = ABSOLUTE(.);
     *(.rtc.data)
     *(.rtc.rodata)
-    *rtc_wake_stub*.o(.data .rodata .data.* .rodata.* .bss .bss.*)
+    *rtc_wake_stub*.*(.data .rodata .data.* .rodata.* .bss .bss.*)
     _rtc_data_end = ABSOLUTE(.);
   } > rtc_slow_seg
 
@@ -30,8 +30,8 @@ SECTIONS
   .rtc.bss (NOLOAD) :
   {
     _rtc_bss_start = ABSOLUTE(.);
-    *rtc_wake_stub*.o(.bss .bss.*)
-    *rtc_wake_stub*.o(COMMON)
+    *rtc_wake_stub*.*(.bss .bss.*)
+    *rtc_wake_stub*.*(COMMON)
     _rtc_bss_end = ABSOLUTE(.);
   } > rtc_slow_seg
 
@@ -83,17 +83,17 @@ SECTIONS
     _iram_text_start = ABSOLUTE(.);
     *(.iram1 .iram1.*)
     *libfreertos.a:(.literal .text .literal.* .text.*)
-    *libheap.a:multi_heap.o(.literal .text .literal.* .text.*)
-    *libheap.a:multi_heap_poisoning.o(.literal .text .literal.* .text.*)
-    *libesp32.a:panic.o(.literal .text .literal.* .text.*)
-    *libesp32.a:core_dump.o(.literal .text .literal.* .text.*)
+    *libheap.a:multi_heap.*(.literal .text .literal.* .text.*)
+    *libheap.a:multi_heap_poisoning.*(.literal .text .literal.* .text.*)
+    *libesp32.a:panic.*(.literal .text .literal.* .text.*)
+    *libesp32.a:core_dump.*(.literal .text .literal.* .text.*)
     *libapp_trace.a:(.literal .text .literal.* .text.*)
-    *libxtensa-debug-module.a:eri.o(.literal .text .literal.* .text.*)
+    *libxtensa-debug-module.a:eri.*(.literal .text .literal.* .text.*)
     *librtc.a:(.literal .text .literal.* .text.*)
     *libsoc.a:(.literal .text .literal.* .text.*)
     *libhal.a:(.literal .text .literal.* .text.*)
-    *libgcc.a:lib2funcs.o(.literal .text .literal.* .text.*)
-    *libspi_flash.a:spi_flash_rom_patch.o(.literal .text .literal.* .text.*)
+    *libgcc.a:lib2funcs.*(.literal .text .literal.* .text.*)
+    *libspi_flash.a:spi_flash_rom_patch.*(.literal .text .literal.* .text.*)
     *libgcov.a:(.literal .text .literal.* .text.*)
     INCLUDE esp32.spiram.rom-functions-iram.ld
     _iram_text_end = ABSOLUTE(.);
@@ -114,13 +114,13 @@ SECTIONS
     *(.gnu.linkonce.s2.*)
     *(.jcr)
     *(.dram1 .dram1.*)
-    *libesp32.a:panic.o(.rodata .rodata.*)
+    *libesp32.a:panic.*(.rodata .rodata.*)
     *libphy.a:(.rodata .rodata.*)
-    *libsoc.a:rtc_clk.o(.rodata .rodata.*)
+    *libsoc.a:rtc_clk.*(.rodata .rodata.*)
     *libapp_trace.a:(.rodata .rodata.*)
     *libgcov.a:(.rodata .rodata.*)
-    *libheap.a:multi_heap.o(.rodata .rodata.*)
-    *libheap.a:multi_heap_poisoning.o(.rodata .rodata.*)
+    *libheap.a:multi_heap.*(.rodata .rodata.*)
+    *libheap.a:multi_heap_poisoning.*(.rodata .rodata.*)
     INCLUDE esp32.spiram.rom-functions-dram.ld
     _data_end = ABSOLUTE(.);
     . = ALIGN(4);
@@ -169,13 +169,13 @@ SECTIONS
     . = (. + 7) & ~ 3;
     /*  C++ constructor and destructor tables, properly ordered:  */
     __init_array_start = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.ctors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .ctors))
+    KEEP (*crtbegin.*(.ctors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .ctors))
     KEEP (*(SORT(.ctors.*)))
     KEEP (*(.ctors))
     __init_array_end = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.dtors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .dtors))
+    KEEP (*crtbegin.*(.dtors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .dtors))
     KEEP (*(SORT(.dtors.*)))
     KEEP (*(.dtors))
     /*  C++ exception handlers table:  */

From 2816cf1d67b4f3bd4df50dfbacda33ec54d4958e Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 1 Mar 2018 18:41:15 +1100
Subject: [PATCH 034/112] cmake: Change data_file_to_c to data_file_embed_asm
 for objcopy compatibility

Now generates _binary_filename_start / _binary_filename_end as well as more useful naming.
---
 tools/cmake/scripts/data_file_embed_asm.cmake | 82 +++++++++++++++++++
 tools/cmake/scripts/data_file_to_c.cmake      | 56 -------------
 tools/cmake/utilities.cmake                   |  5 +-
 3 files changed, 85 insertions(+), 58 deletions(-)
 create mode 100644 tools/cmake/scripts/data_file_embed_asm.cmake
 delete mode 100644 tools/cmake/scripts/data_file_to_c.cmake

diff --git a/tools/cmake/scripts/data_file_embed_asm.cmake b/tools/cmake/scripts/data_file_embed_asm.cmake
new file mode 100644
index 000000000..76a1fe298
--- /dev/null
+++ b/tools/cmake/scripts/data_file_embed_asm.cmake
@@ -0,0 +1,82 @@
+#
+# Convert a file (text or binary) into an assembler source file suitable
+# for gcc. Designed to replicate 'objcopy' with more predictable
+# naming, and supports appending a null byte for embedding text as
+# a string.
+#
+# Designed to be run as a script with "cmake -P"
+#
+# Set variables DATA_FILE, SOURCE_FILE, FILE_TYPE when running this.
+#
+# If FILE_TYPE is set to STRING, a null byte is appended to DATA_FILE's contents
+# before SOURCE_FILE is created.
+#
+# If FILE_TYPE is unset (or any other value), DATA_FILE is copied
+# verbatim into SOURCE_FILE.
+#
+#
+if(NOT DATA_FILE)
+    message(FATAL_ERROR "DATA_FILE for converting must be specified")
+endif()
+
+if(NOT SOURCE_FILE)
+    message(FATAL_ERROR "SOURCE_FILE destination must be specified")
+endif()
+
+file(READ "${DATA_FILE}" data HEX)
+
+string(LENGTH "${data}" data_len)
+math(EXPR data_len "${data_len} / 2")  # 2 hex bytes per byte
+
+if(FILE_TYPE STREQUAL "TEXT")
+    set(data "${data}00")  # null-byte termination
+endif()
+
+## Convert string of raw hex bytes to lines of hex bytes as gcc .byte expressions
+string(REGEX REPLACE "................................" ".byte \\0\n" data "${data}")  # 16 bytes per line
+string(REGEX REPLACE "[^\n]+$" ".byte \\0\n" data "${data}")                           # last line
+string(REGEX REPLACE "[0-9a-f][0-9a-f]" "0x\\0, " data "${data}")                      # hex formatted C bytes
+string(REGEX REPLACE ", \n" "\n" data "${data}")                                       # trim the last comma
+
+## Come up with C-friendly symbol name based on source file
+get_filename_component(source_filename "${DATA_FILE}" NAME)
+string(MAKE_C_IDENTIFIER "${source_filename}" varname)
+
+function(append str)
+    file(APPEND "${SOURCE_FILE}" "${str}")
+endfunction()
+
+function(append_line str)
+    append("${str}\n")
+endfunction()
+
+function(append_identifier symbol)
+append_line("\n.global ${symbol}")
+append("${symbol}:")
+if(${ARGC} GREATER 1) # optional comment
+    append(" /* ${ARGV1} */")
+endif()
+append("\n")
+endfunction()
+
+file(WRITE "${SOURCE_FILE}" "/*")
+append_line(" * Data converted from ${DATA_FILE}")
+if(FILE_TYPE STREQUAL "TEXT")
+    append_line(" * (null byte appended)")
+endif()
+append_line(" */")
+
+append_line(".data")
+append_identifier("${varname}")
+append_identifier("_binary_${varname}_start" "for objcopy compatibility")
+append("${data}")
+
+append_identifier("_binary_${varname}_end" "for objcopy compatibility")
+
+append_line("")
+if(FILE_TYPE STREQUAL "TEXT")
+    append_identifier("${varname}_length" "not including null byte")
+else()
+    append_identifier("${varname}_length")
+endif()
+append_line(".word ${data_len}")
diff --git a/tools/cmake/scripts/data_file_to_c.cmake b/tools/cmake/scripts/data_file_to_c.cmake
deleted file mode 100644
index fb93bfddc..000000000
--- a/tools/cmake/scripts/data_file_to_c.cmake
+++ /dev/null
@@ -1,56 +0,0 @@
-#
-# Convert a file (text or binary) into a C source file suitable
-# for gcc. Designed to replicate 'objcopy' with more predictable
-# naming, and supports appending a null byte for embedding text as
-# a string.
-#
-# Designed to be run as a script with "cmake -P"
-#
-# Set variables DATA_FILE, SOURCE_FILE, FILE_TYPE when running this.
-#
-# If FILE_TYPE is set to STRING, a null byte is appended to DATA_FILE's contents
-# before it is embedded.
-#
-# If FILE_TYPE is unset (or any other value), DATA_FILE is embedded
-# verbatim.
-#
-#
-if(NOT DATA_FILE)
-    message(FATAL_ERROR "DATA_FILE for converting must be specified")
-endif()
-
-if(NOT SOURCE_FILE)
-    message(FATAL_ERROR "SOURCE_FILE destination must be specified")
-endif()
-
-file(READ "${DATA_FILE}" data HEX)
-
-if(FILE_TYPE STREQUAL "TEXT")
-    set(data "${data}00")  # null-byte terimnation
-endif()
-
-## Convert string of raw hex bytes to lines of hex bytes in C array format
-string(REGEX REPLACE "................................" "\\0\n    " data "${data}")  # 16 bytes per line
-string(REGEX REPLACE "[0-9a-f][0-9a-f]" "0x\\0, " data "${data}")                    # hex formatted C bytes
-string(REGEX REPLACE ", $" "" data "${data}")                                        # trim the last comma (cosmetic)
-
-## Come up with C-friendly name for file
-get_filename_component(source_filename "${DATA_FILE}" NAME)
-string(MAKE_C_IDENTIFIER "${source_filename}" varname)
-
-file(WRITE "${SOURCE_FILE}"  "/*\n")
-file(APPEND "${SOURCE_FILE}" " * Data converted from ${DATA_FILE}\n")
-if(FILE_TYPE STREQUAL "TEXT")
-    file(APPEND "${SOURCE_FILE}" " * (null byte appended)\n")
-endif()
-file(APPEND "${SOURCE_FILE}" " */\n")
-file(APPEND "${SOURCE_FILE}" "#include <stdlib.h>\n")
-file(APPEND "${SOURCE_FILE}" "#include <stddef.h>\n\n")
-
-file(APPEND "${SOURCE_FILE}" "const char ${varname}[] = {\n    ${data}\n    };\n")
-file(APPEND "${SOURCE_FILE}" "const size_t ${varname}_length = sizeof(${varname});\n\n")
-
-# Backwards compatibility, matches objcopy binary symbol names
-file(APPEND "${SOURCE_FILE}" "/* Backwards compatible names, match objcopy -I binary naming */\n")
-file(APPEND "${SOURCE_FILE}" "const char *_binary_${varname}_start = ${varname};\n")
-file(APPEND "${SOURCE_FILE}" "const char *_binary_${varname}_end = ${varname} + sizeof(${varname});\n")
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index ec6323d90..f3c0c1981 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -106,15 +106,16 @@ function(target_add_binary_data target embed_file embed_type)
     get_filename_component(embed_file "${embed_file}" ABSOLUTE)
 
     get_filename_component(name "${embed_file}" NAME)
-    set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.c")
+    set(embed_srcfile "${CMAKE_BINARY_DIR}/${name}.S")
 
     add_custom_command(OUTPUT "${embed_srcfile}"
         COMMAND "${CMAKE_COMMAND}"
         -D "DATA_FILE=${embed_file}"
         -D "SOURCE_FILE=${embed_srcfile}"
         -D "FILE_TYPE=${embed_type}"
-        -P "${IDF_PATH}/tools/cmake/scripts/data_file_to_c.cmake"
+        -P "${IDF_PATH}/tools/cmake/scripts/data_file_embed_asm.cmake"
         MAIN_DEPENDENCY "${embed_file}"
+        DEPENDENCIES "${IDF_PATH}/tools/cmake/scripts/data_file_embed_asm.cmake"
         WORKING_DIRECTORY "${CMAKE_BINARY_DIR}")
 
     set_property(DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}" APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES "${embed_srcfile}")

From 9d88d13f77b64db0f9f920413aee2ef8ea28b3a7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 1 Mar 2018 18:41:40 +1100
Subject: [PATCH 035/112] cmake: convert_to_cmake.py script for converting IDF
 GNU Make projects

---
 tools/cmake/convert_to_cmake.py | 214 ++++++++++++++++++++++++++++++++
 1 file changed, 214 insertions(+)
 create mode 100755 tools/cmake/convert_to_cmake.py

diff --git a/tools/cmake/convert_to_cmake.py b/tools/cmake/convert_to_cmake.py
new file mode 100755
index 000000000..0cfd60263
--- /dev/null
+++ b/tools/cmake/convert_to_cmake.py
@@ -0,0 +1,214 @@
+#!/usr/bin/env python
+#
+# Command line tool to convert simple ESP-IDF Makefile & component.mk files to
+# CMakeLists.txt files
+#
+import argparse
+import subprocess
+import re
+import os.path
+import glob
+import sys
+
+debug = False
+
+def get_make_variables(path, makefile="Makefile", expected_failure=False, variables={}):
+    """
+    Given the path to a Makefile of some kind, return a dictionary of all variables defined in this Makefile
+
+    Uses 'make' to parse the Makefile syntax, so we don't have to!
+
+    Overrides IDF_PATH= to avoid recursively evaluating the entire project Makefile structure.
+    """
+    variable_setters = [ ("%s=%s" % (k,v)) for (k,v) in variables.items() ]
+
+    cmdline = ["make", "-rpn", "-C", path, "-f", makefile ] + variable_setters
+    if debug:
+        print("Running %s..." % (" ".join(cmdline)))
+
+    p = subprocess.Popen(cmdline, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    (output, stderr) = p.communicate("\n")
+
+    if (not expected_failure) and p.returncode != 0:
+        raise RuntimeError("Unexpected make failure, result %d" % p.returncode)
+
+    if debug:
+        print("Make stdout:")
+        print(output)
+        print("Make stderr:")
+        print(stderr)
+
+    next_is_makefile = False  # is the next line a makefile variable?
+    result = {}
+    BUILT_IN_VARS = set(["MAKEFILE_LIST", "SHELL", "CURDIR", "MAKEFLAGS"])
+
+    for line in output.decode().split("\n"):
+        if line.startswith("# makefile"):  # this line appears before any variable defined in the makefile itself
+            next_is_makefile = True
+        elif next_is_makefile:
+            next_is_makefile = False
+            m = re.match(r"(?P<var>[^ ]+) :?= (?P<val>.+)", line)
+            if m is not None:
+                if not m.group("var") in BUILT_IN_VARS:
+                    result[m.group("var")] = m.group("val").strip()
+
+    return result
+
+def get_component_variables(project_path, component_path):
+    make_vars = get_make_variables(component_path,
+                                   os.path.join(os.environ["IDF_PATH"],
+                                                "make",
+                                                "component_wrapper.mk"),
+                                   expected_failure=True,
+                                   variables = {
+                                       "COMPONENT_MAKEFILE" : os.path.join(component_path, "component.mk"),
+                                       "COMPONENT_NAME" : os.path.basename(component_path),
+                                       "PROJECT_PATH": project_path,
+                                   })
+
+    if "COMPONENT_OBJS" in make_vars:  # component.mk specifies list of object files
+        # Convert to sources
+        def find_src(obj):
+            obj = os.path.splitext(obj)[0]
+            for ext in [ "c", "cpp", "S" ]:
+                if os.path.exists(os.path.join(component_path, obj) + "." + ext):
+                    return obj + "." + ext
+            print("WARNING: Can't find source file for component %s COMPONENT_OBJS %s" % (component_path, obj))
+            return None
+
+        srcs = []
+        for obj in make_vars["COMPONENT_OBJS"].split(" "):
+            src = find_src(obj)
+            if src is not None:
+                srcs.append(src)
+        make_vars["COMPONENT_SRCS"] = " ".join(srcs)
+    else:  # Use COMPONENT_SRCDIRS
+        make_vars["COMPONENT_SRCDIRS"] = make_vars.get("COMPONENT_SRCDIRS", ".")
+
+    make_vars["COMPONENT_ADD_INCLUDEDIRS"] = make_vars.get("COMPONENT_ADD_INCLUDEDIRS", "include")
+
+    return make_vars
+
+
+def convert_project(project_path):
+    if not os.path.exists(project_path):
+        raise RuntimeError("Project directory '%s' not found" % project_path)
+    if not os.path.exists(os.path.join(project_path, "Makefile")):
+        raise RuntimeError("Directory '%s' doesn't contain a project Makefile" % project_path)
+
+    project_cmakelists = os.path.join(project_path, "CMakeLists.txt")
+    if os.path.exists(project_cmakelists):
+        raise RuntimeError("This project already has a CMakeLists.txt file")
+
+    project_vars = get_make_variables(project_path, expected_failure=True)
+    if not "PROJECT_NAME" in project_vars:
+        raise RuntimeError("PROJECT_NAME does not appear to be defined in IDF project Makefile at %s" % project_path)
+
+    component_paths = project_vars["COMPONENT_PATHS"].split(" ")
+
+    # "main" component is made special in cmake, so extract it from the component_paths list
+    try:
+        main_component_path = [ p for p in component_paths if os.path.basename(p) == "main" ][0]
+        if debug:
+            print("Found main component %s"  % main_component_path)
+        main_vars = get_component_variables(project_path, main_component_path)
+    except IndexError:
+        print("WARNING: Project has no 'main' component, but CMake-based system requires at least one file in MAIN_SRCS...")
+        main_vars = { "COMPONENT_SRCS" : ""} # dummy for MAIN_SRCS
+
+    # Remove main component from list of components we're converting to cmake
+    component_paths = [ p for p in component_paths if os.path.basename(p) != "main" ]
+
+    # Convert components as needed
+    for p in component_paths:
+        convert_component(project_path, p)
+
+    # Look up project variables before we start writing the file, so nothing
+    # is created if there is an error
+
+    main_srcs = main_vars["COMPONENT_SRCS"].split(" ")
+    # convert from component-relative to absolute paths
+    main_srcs = [ os.path.normpath(os.path.join(main_component_path, m)) for m in main_srcs ]
+    # convert to make relative to the project directory
+    main_srcs = [ os.path.relpath(m, project_path) for m in main_srcs ]
+
+    project_name = project_vars["PROJECT_NAME"]
+
+    # Generate the project CMakeLists.txt file
+    with open(project_cmakelists, "w") as f:
+        f.write("""
+# (Automatically converted from project Makefile by convert_to_cmake.py.)
+
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+""")
+        f.write("set(MAIN_SRCS %s)\n" % " ".join(main_srcs))
+        f.write("""
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+""")
+        f.write("project(%s)\n" % project_name)
+
+    print("Converted project %s" % project_cmakelists)
+
+def convert_component(project_path, component_path):
+    if debug:
+        print("Converting %s..." % (component_path))
+    cmakelists_path = os.path.join(component_path, "CMakeLists.txt")
+    if os.path.exists(cmakelists_path):
+        print("Skipping already-converted component %s..." % cmakelists_path)
+        return
+    v = get_component_variables(project_path, component_path)
+
+    # Look up all the variables before we start writing the file, so it's not
+    # created if there's an erro
+    component_srcs = v.get("COMPONENT_SRCS", None)
+    component_srcdirs = None
+    if component_srcs is not None:
+        # see if we should be using COMPONENT_SRCS or COMPONENT_SRCDIRS, if COMPONENT_SRCS is everything in SRCDIRS
+        component_allsrcs = []
+        for d in v.get("COMPONENT_SRCDIRS", "").split(" "):
+            component_allsrcs += glob.glob(os.path.normpath(os.path.join(component_path, d, "*.[cS]")))
+            component_allsrcs += glob.glob(os.path.normpath(os.path.join(component_path, d, "*.cpp")))
+        abs_component_srcs = [os.path.normpath(os.path.join(component_path, p)) for p in component_srcs.split(" ")]
+        if set(component_allsrcs) == set(abs_component_srcs):
+            component_srcdirs = v.get("COMPONENT_SRCDIRS")
+
+    component_add_includedirs = v["COMPONENT_ADD_INCLUDEDIRS"]
+    cflags = v.get("CFLAGS", None)
+
+    with open(cmakelists_path, "w") as f:
+        f.write("set(COMPONENT_ADD_INCLUDEDIRS %s)\n\n" % component_add_includedirs)
+        if component_srcdirs is not None:
+            f.write("set(COMPONENT_SRCDIRS %s)\n\n" % component_srcdirs)
+            f.write("register_component()\n")
+        elif component_srcs is not None:
+            f.write("set(COMPONENT_SRCS %s)\n\n" % component_srcs)
+            f.write("register_component()\n")
+        else:
+            f.write("register_config_only_component()\n")
+        if cflags is not None:
+            f.write("component_compile_options(%s)\n" % cflags)
+
+    print("Converted %s" % cmakelists_path)
+
+
+def main():
+    global debug
+
+    parser = argparse.ArgumentParser(description='convert_to_cmake.py - ESP-IDF Project Makefile to CMakeLists.txt converter', prog='convert_to_cmake')
+
+    parser.add_argument('--debug', help='Display debugging output',
+                        action='store_true')
+
+    parser.add_argument('project', help='Path to project to convert (defaults to CWD)', default=os.getcwd(), metavar='project path', nargs='?')
+
+    args = parser.parse_args()
+    debug = args.debug
+    print("Converting %s..." % args.project)
+    convert_project(args.project)
+
+
+if __name__ == "__main__":
+    main()

From 800bffb8b007dfafd09c667e8fb019fb38b7a1d1 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 27 Feb 2018 17:44:31 +1100
Subject: [PATCH 036/112] cmake: Add CMakeLists.txt files for all examples

Generating using convert_to_cmake.py, with some minor cleanup
---
 components/app_trace/CMakeLists.txt           | 19 +++++++++++-
 components/bt/CMakeLists.txt                  | 30 +++++--------------
 examples/bluetooth/a2dp_sink/CMakeLists.txt   | 12 ++++++++
 examples/bluetooth/a2dp_source/CMakeLists.txt | 11 +++++++
 examples/bluetooth/ble_adv/CMakeLists.txt     | 10 +++++++
 .../bluetooth/ble_eddystone/CMakeLists.txt    |  8 +++++
 examples/bluetooth/ble_ibeacon/CMakeLists.txt |  8 +++++
 .../bluetooth/ble_spp_client/CMakeLists.txt   |  8 +++++
 .../bluetooth/ble_spp_server/CMakeLists.txt   |  8 +++++
 examples/bluetooth/blufi/CMakeLists.txt       |  8 +++++
 .../bluetooth/bt_discovery/CMakeLists.txt     |  8 +++++
 .../bluetooth/bt_spp_acceptor/CMakeLists.txt  |  8 +++++
 .../bluetooth/bt_spp_initiator/CMakeLists.txt |  8 +++++
 .../controller_hci_uart/CMakeLists.txt        |  8 +++++
 examples/bluetooth/gatt_client/CMakeLists.txt |  8 +++++
 .../gatt_security_client/CMakeLists.txt       |  8 +++++
 .../gatt_security_server/CMakeLists.txt       |  8 +++++
 examples/bluetooth/gatt_server/CMakeLists.txt |  8 +++++
 .../gatt_server_service_table/CMakeLists.txt  |  8 +++++
 .../gattc_multi_connect/CMakeLists.txt        |  8 +++++
 examples/ethernet/ethernet/CMakeLists.txt     |  8 +++++
 .../get-started/hello_world/CMakeLists.txt    |  2 +-
 examples/peripherals/adc/CMakeLists.txt       |  8 +++++
 examples/peripherals/adc2/CMakeLists.txt      |  8 +++++
 examples/peripherals/gpio/CMakeLists.txt      |  8 +++++
 examples/peripherals/i2c/CMakeLists.txt       |  8 +++++
 examples/peripherals/i2s/CMakeLists.txt       |  8 +++++
 .../peripherals/i2s_adc_dac/CMakeLists.txt    |  8 +++++
 examples/peripherals/ledc/CMakeLists.txt      |  8 +++++
 examples/peripherals/pcnt/CMakeLists.txt      |  8 +++++
 .../peripherals/rmt_nec_tx_rx/CMakeLists.txt  |  8 +++++
 examples/peripherals/rmt_tx/CMakeLists.txt    |  8 +++++
 .../peripherals/sigmadelta/CMakeLists.txt     |  8 +++++
 .../peripherals/spi_master/CMakeLists.txt     |  8 +++++
 .../peripherals/timer_group/CMakeLists.txt    |  8 +++++
 .../touch_pad_interrupt/CMakeLists.txt        |  8 +++++
 .../peripherals/touch_pad_read/CMakeLists.txt |  8 +++++
 .../uart_async_rxtxtasks/CMakeLists.txt       |  8 +++++
 examples/peripherals/uart_echo/CMakeLists.txt |  8 +++++
 .../peripherals/uart_events/CMakeLists.txt    |  8 +++++
 .../aws_iot/subscribe_publish/CMakeLists.txt  |  4 +--
 .../aws_iot/thing_shadow/CMakeLists.txt       | 13 ++++++++
 examples/protocols/coap_client/CMakeLists.txt |  8 +++++
 examples/protocols/coap_server/CMakeLists.txt |  8 +++++
 .../protocols/http2_request/CMakeLists.txt    |  8 +++++
 .../components/sh2lib/CMakeLists.txt          |  5 ++++
 .../protocols/http_request/CMakeLists.txt     |  8 +++++
 .../protocols/https_request/CMakeLists.txt    | 14 +++++++++
 examples/protocols/mdns/CMakeLists.txt        |  8 +++++
 .../protocols/openssl_client/CMakeLists.txt   |  8 +++++
 .../protocols/openssl_server/CMakeLists.txt   | 12 ++++++++
 .../protocols/pppos_client/CMakeLists.txt     |  8 +++++
 examples/protocols/sntp/CMakeLists.txt        |  8 +++++
 .../protocols/udp_multicast/CMakeLists.txt    |  8 +++++
 examples/storage/nvs_rw_blob/CMakeLists.txt   |  8 +++++
 examples/storage/nvs_rw_value/CMakeLists.txt  |  8 +++++
 examples/storage/sd_card/CMakeLists.txt       |  8 +++++
 examples/storage/spiffs/CMakeLists.txt        |  8 +++++
 .../storage/wear_levelling/CMakeLists.txt     |  8 +++++
 .../system/app_trace_to_host/CMakeLists.txt   |  8 +++++
 .../system/base_mac_address/CMakeLists.txt    |  8 +++++
 examples/system/console/CMakeLists.txt        |  8 +++++
 examples/system/deep_sleep/CMakeLists.txt     |  8 +++++
 examples/system/gcov/CMakeLists.txt           |  8 +++++
 examples/system/ota/CMakeLists.txt            |  8 +++++
 examples/system/task_watchdog/CMakeLists.txt  |  8 +++++
 examples/wifi/espnow/CMakeLists.txt           |  8 +++++
 examples/wifi/iperf/CMakeLists.txt            |  8 +++++
 examples/wifi/iperf/components/CMakeLists.txt |  5 ++++
 examples/wifi/power_save/CMakeLists.txt       |  8 +++++
 examples/wifi/scan/CMakeLists.txt             |  8 +++++
 examples/wifi/smart_config/CMakeLists.txt     |  8 +++++
 examples/wifi/wpa2_enterprise/CMakeLists.txt  | 17 +++++++++++
 examples/wifi/wps/CMakeLists.txt              |  8 +++++
 74 files changed, 615 insertions(+), 27 deletions(-)
 create mode 100755 examples/bluetooth/a2dp_sink/CMakeLists.txt
 create mode 100755 examples/bluetooth/a2dp_source/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_adv/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_eddystone/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_ibeacon/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_spp_client/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_spp_server/CMakeLists.txt
 create mode 100644 examples/bluetooth/blufi/CMakeLists.txt
 create mode 100644 examples/bluetooth/bt_discovery/CMakeLists.txt
 create mode 100644 examples/bluetooth/bt_spp_acceptor/CMakeLists.txt
 create mode 100644 examples/bluetooth/bt_spp_initiator/CMakeLists.txt
 create mode 100644 examples/bluetooth/controller_hci_uart/CMakeLists.txt
 create mode 100644 examples/bluetooth/gatt_client/CMakeLists.txt
 create mode 100644 examples/bluetooth/gatt_security_client/CMakeLists.txt
 create mode 100644 examples/bluetooth/gatt_security_server/CMakeLists.txt
 create mode 100644 examples/bluetooth/gatt_server/CMakeLists.txt
 create mode 100644 examples/bluetooth/gatt_server_service_table/CMakeLists.txt
 create mode 100644 examples/bluetooth/gattc_multi_connect/CMakeLists.txt
 create mode 100644 examples/ethernet/ethernet/CMakeLists.txt
 create mode 100644 examples/peripherals/adc/CMakeLists.txt
 create mode 100644 examples/peripherals/adc2/CMakeLists.txt
 create mode 100644 examples/peripherals/gpio/CMakeLists.txt
 create mode 100644 examples/peripherals/i2c/CMakeLists.txt
 create mode 100644 examples/peripherals/i2s/CMakeLists.txt
 create mode 100644 examples/peripherals/i2s_adc_dac/CMakeLists.txt
 create mode 100644 examples/peripherals/ledc/CMakeLists.txt
 create mode 100644 examples/peripherals/pcnt/CMakeLists.txt
 create mode 100644 examples/peripherals/rmt_nec_tx_rx/CMakeLists.txt
 create mode 100644 examples/peripherals/rmt_tx/CMakeLists.txt
 create mode 100644 examples/peripherals/sigmadelta/CMakeLists.txt
 create mode 100644 examples/peripherals/spi_master/CMakeLists.txt
 create mode 100644 examples/peripherals/timer_group/CMakeLists.txt
 create mode 100644 examples/peripherals/touch_pad_interrupt/CMakeLists.txt
 create mode 100644 examples/peripherals/touch_pad_read/CMakeLists.txt
 create mode 100644 examples/peripherals/uart_async_rxtxtasks/CMakeLists.txt
 create mode 100644 examples/peripherals/uart_echo/CMakeLists.txt
 create mode 100644 examples/peripherals/uart_events/CMakeLists.txt
 create mode 100644 examples/protocols/aws_iot/thing_shadow/CMakeLists.txt
 create mode 100644 examples/protocols/coap_client/CMakeLists.txt
 create mode 100644 examples/protocols/coap_server/CMakeLists.txt
 create mode 100644 examples/protocols/http2_request/CMakeLists.txt
 create mode 100644 examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
 create mode 100644 examples/protocols/http_request/CMakeLists.txt
 create mode 100644 examples/protocols/https_request/CMakeLists.txt
 create mode 100644 examples/protocols/mdns/CMakeLists.txt
 create mode 100644 examples/protocols/openssl_client/CMakeLists.txt
 create mode 100644 examples/protocols/openssl_server/CMakeLists.txt
 create mode 100644 examples/protocols/pppos_client/CMakeLists.txt
 create mode 100644 examples/protocols/sntp/CMakeLists.txt
 create mode 100644 examples/protocols/udp_multicast/CMakeLists.txt
 create mode 100644 examples/storage/nvs_rw_blob/CMakeLists.txt
 create mode 100644 examples/storage/nvs_rw_value/CMakeLists.txt
 create mode 100644 examples/storage/sd_card/CMakeLists.txt
 create mode 100644 examples/storage/spiffs/CMakeLists.txt
 create mode 100644 examples/storage/wear_levelling/CMakeLists.txt
 create mode 100644 examples/system/app_trace_to_host/CMakeLists.txt
 create mode 100644 examples/system/base_mac_address/CMakeLists.txt
 create mode 100644 examples/system/console/CMakeLists.txt
 create mode 100644 examples/system/deep_sleep/CMakeLists.txt
 create mode 100644 examples/system/gcov/CMakeLists.txt
 create mode 100644 examples/system/ota/CMakeLists.txt
 create mode 100644 examples/system/task_watchdog/CMakeLists.txt
 create mode 100644 examples/wifi/espnow/CMakeLists.txt
 create mode 100644 examples/wifi/iperf/CMakeLists.txt
 create mode 100644 examples/wifi/iperf/components/CMakeLists.txt
 create mode 100644 examples/wifi/power_save/CMakeLists.txt
 create mode 100644 examples/wifi/scan/CMakeLists.txt
 create mode 100644 examples/wifi/smart_config/CMakeLists.txt
 create mode 100644 examples/wifi/wpa2_enterprise/CMakeLists.txt
 create mode 100644 examples/wifi/wps/CMakeLists.txt

diff --git a/components/app_trace/CMakeLists.txt b/components/app_trace/CMakeLists.txt
index ba2fa9c7e..ebdfd941c 100644
--- a/components/app_trace/CMakeLists.txt
+++ b/components/app_trace/CMakeLists.txt
@@ -1,4 +1,21 @@
-set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_SRCDIRS "." "gcov")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+if (CONFIG_SYSVIEW_ENABLE)
+    list(APPEND COMPONENT_ADD_INCLUDEDIRS
+        sys_view/Config
+        sys_view/SEGGER
+        sys_view/Sample/OS)
+
+    list(APPEND COMPONENT_SRCDIRS
+        "sys_view/SEGGER"
+        "sys_view/Sample/OS"
+        "sys_view/Sample/Config"
+        "sys_view/esp32")
+endif()
+
 register_component()
+
+# disable --coverage for this component, as it is used as transport
+# for gcov
+component_compile_options("-fno-profile-arcs" "-fno-test-coverage")
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index f50c58ab0..f802be0f1 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -5,35 +5,24 @@ endif()
 set(COMPONENT_SRCDIRS .)
 set(COMPONENT_ADD_INCLUDEDIRS include)
 
-target_link_libraries("-L ${CMAKE_CURRENT_LIST_DIR}/lib")
-target_link_libraries(bt btdm_app)
-
 if(CONFIG_BLUEDROID_ENABLED)
 
-    set(COMPONENT_ADD_INCLUDEDIRS ${COMPONENT_ADD_INCLUDEDIRS}
+    list(APPEND COMPONENT_ADD_INCLUDEDIRS
         bluedroid/bta/include
         bluedroid/bta/sys/include
         bluedroid/btcore/include
         bluedroid/device/include
-        bluedroid/gki/include
         bluedroid/hci/include
         bluedroid/osi/include
-        bluedroid/utils/include
         bluedroid/external/sbc/decoder/include
-        bluedroid/btc/core/include
+		bluedroid/external/sbc/encoder/include
         bluedroid/btc/profile/esp/blufi/include
         bluedroid/btc/profile/esp/include
-        bluedroid/btc/profile/std/gatt/include
-        bluedroid/btc/profile/std/gap/include
         bluedroid/btc/profile/std/a2dp/include
         bluedroid/btc/profile/std/include
         bluedroid/btc/include
-        bluedroid/btif/include
-        bluedroid/stack/btm/include
-        bluedroid/stack/btu/include
         bluedroid/stack/gap/include
         bluedroid/stack/gatt/include
-        bluedroid/stack/hcic/include
         bluedroid/stack/l2cap/include
         bluedroid/stack/sdp/include
         bluedroid/stack/smp/include
@@ -43,11 +32,10 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/stack/a2dp/include
         bluedroid/stack/rfcomm/include
         bluedroid/stack/include
-        bluedroid/utils/include
         bluedroid/api/include
         bluedroid/include)
 
-    set(COMPONENT_SRCDIRS ${COMPONENT_SRCDIRS}
+    list(APPEND COMPONENT_SRCDIRS
         bluedroid/bta/dm
         bluedroid/bta/gatt
         bluedroid/bta/hh
@@ -56,15 +44,14 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/bta/ar
         bluedroid/bta/sys
         bluedroid/bta/jv
-        bluedroid/bta
         bluedroid/btcore
         bluedroid/btif
         bluedroid/device
-        bluedroid/gki
         bluedroid/hci
         bluedroid/main
         bluedroid/osi
         bluedroid/external/sbc/decoder/srce
+	    bluedroid/external/sbc/encoder/srce
         bluedroid/btc/core
         bluedroid/btc/profile/esp/blufi
         bluedroid/btc/profile/std/gap
@@ -72,13 +59,11 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/btc/profile/std/a2dp
         bluedroid/btc/profile/std/avrc
         bluedroid/btc/profile/std/spp
-        bluedroid/btc/profile
         bluedroid/stack/btm
         bluedroid/stack/btu
         bluedroid/stack/gap
         bluedroid/stack/gatt
         bluedroid/stack/hcic
-        bluedroid/stack/include
         bluedroid/stack/l2cap
         bluedroid/stack/sdp
         bluedroid/stack/smp
@@ -87,11 +72,12 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/stack/avdt
         bluedroid/stack/a2dp
         bluedroid/stack/rfcomm
-        bluedroid/stack
-        bluedroid/utils
         bluedroid/api
-        bluedroid)
+        )
 
 endif()
 
 register_component()
+
+target_link_libraries(bt "-L${CMAKE_CURRENT_LIST_DIR}/lib")
+target_link_libraries(bt btdm_app)
diff --git a/examples/bluetooth/a2dp_sink/CMakeLists.txt b/examples/bluetooth/a2dp_sink/CMakeLists.txt
new file mode 100755
index 000000000..4d14857a0
--- /dev/null
+++ b/examples/bluetooth/a2dp_sink/CMakeLists.txt
@@ -0,0 +1,12 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/bt_app_av.c
+    main/bt_app_core.c
+    main/main.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(a2dp_sink)
diff --git a/examples/bluetooth/a2dp_source/CMakeLists.txt b/examples/bluetooth/a2dp_source/CMakeLists.txt
new file mode 100755
index 000000000..1b4c44799
--- /dev/null
+++ b/examples/bluetooth/a2dp_source/CMakeLists.txt
@@ -0,0 +1,11 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/bt_app_core.c
+    main/main.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(a2dp_source)
diff --git a/examples/bluetooth/ble_adv/CMakeLists.txt b/examples/bluetooth/ble_adv/CMakeLists.txt
new file mode 100644
index 000000000..04715a858
--- /dev/null
+++ b/examples/bluetooth/ble_adv/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/app_bt.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ble_adv)
diff --git a/examples/bluetooth/ble_eddystone/CMakeLists.txt b/examples/bluetooth/ble_eddystone/CMakeLists.txt
new file mode 100644
index 000000000..05d77c7c6
--- /dev/null
+++ b/examples/bluetooth/ble_eddystone/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/esp_eddystone_api.c main/esp_eddystone_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ble_eddystone_demo)
diff --git a/examples/bluetooth/ble_ibeacon/CMakeLists.txt b/examples/bluetooth/ble_ibeacon/CMakeLists.txt
new file mode 100644
index 000000000..5eb1d7363
--- /dev/null
+++ b/examples/bluetooth/ble_ibeacon/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ibeacon_demo.c main/esp_ibeacon_api.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ble_ibeacon_demo)
diff --git a/examples/bluetooth/ble_spp_client/CMakeLists.txt b/examples/bluetooth/ble_spp_client/CMakeLists.txt
new file mode 100644
index 000000000..93abbbfb3
--- /dev/null
+++ b/examples/bluetooth/ble_spp_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/spp_client_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spp_client_demo)
diff --git a/examples/bluetooth/ble_spp_server/CMakeLists.txt b/examples/bluetooth/ble_spp_server/CMakeLists.txt
new file mode 100644
index 000000000..c0508f801
--- /dev/null
+++ b/examples/bluetooth/ble_spp_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ble_spp_server_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ble_spp_server_demo)
diff --git a/examples/bluetooth/blufi/CMakeLists.txt b/examples/bluetooth/blufi/CMakeLists.txt
new file mode 100644
index 000000000..e016e161a
--- /dev/null
+++ b/examples/bluetooth/blufi/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/blufi_security.c main/blufi_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(blufi_demo)
diff --git a/examples/bluetooth/bt_discovery/CMakeLists.txt b/examples/bluetooth/bt_discovery/CMakeLists.txt
new file mode 100644
index 000000000..b79d221bd
--- /dev/null
+++ b/examples/bluetooth/bt_discovery/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/bt_discovery.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_discovery)
diff --git a/examples/bluetooth/bt_spp_acceptor/CMakeLists.txt b/examples/bluetooth/bt_spp_acceptor/CMakeLists.txt
new file mode 100644
index 000000000..5ed97b387
--- /dev/null
+++ b/examples/bluetooth/bt_spp_acceptor/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/example_spp_acceptor_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_spp_acceptor_demo)
diff --git a/examples/bluetooth/bt_spp_initiator/CMakeLists.txt b/examples/bluetooth/bt_spp_initiator/CMakeLists.txt
new file mode 100644
index 000000000..fc8eb551b
--- /dev/null
+++ b/examples/bluetooth/bt_spp_initiator/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/example_spp_initiator_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_spp_initiator_demo)
diff --git a/examples/bluetooth/controller_hci_uart/CMakeLists.txt b/examples/bluetooth/controller_hci_uart/CMakeLists.txt
new file mode 100644
index 000000000..0c7fcbdd9
--- /dev/null
+++ b/examples/bluetooth/controller_hci_uart/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/controller_hci_uart_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(controller_hci_uart)
diff --git a/examples/bluetooth/gatt_client/CMakeLists.txt b/examples/bluetooth/gatt_client/CMakeLists.txt
new file mode 100644
index 000000000..5e41444ab
--- /dev/null
+++ b/examples/bluetooth/gatt_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gattc_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gatt_client_demo)
diff --git a/examples/bluetooth/gatt_security_client/CMakeLists.txt b/examples/bluetooth/gatt_security_client/CMakeLists.txt
new file mode 100644
index 000000000..787f0b763
--- /dev/null
+++ b/examples/bluetooth/gatt_security_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/example_ble_sec_gattc_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sec_gattc_demo)
diff --git a/examples/bluetooth/gatt_security_server/CMakeLists.txt b/examples/bluetooth/gatt_security_server/CMakeLists.txt
new file mode 100644
index 000000000..d232d02b3
--- /dev/null
+++ b/examples/bluetooth/gatt_security_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/example_ble_sec_gatts_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sec_gatts_demo)
diff --git a/examples/bluetooth/gatt_server/CMakeLists.txt b/examples/bluetooth/gatt_server/CMakeLists.txt
new file mode 100644
index 000000000..74a0560be
--- /dev/null
+++ b/examples/bluetooth/gatt_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gatts_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gatt_server_demos)
diff --git a/examples/bluetooth/gatt_server_service_table/CMakeLists.txt b/examples/bluetooth/gatt_server_service_table/CMakeLists.txt
new file mode 100644
index 000000000..2f5653065
--- /dev/null
+++ b/examples/bluetooth/gatt_server_service_table/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gatts_table_creat_demo.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gatt_server_service_table_demo)
diff --git a/examples/bluetooth/gattc_multi_connect/CMakeLists.txt b/examples/bluetooth/gattc_multi_connect/CMakeLists.txt
new file mode 100644
index 000000000..73566a731
--- /dev/null
+++ b/examples/bluetooth/gattc_multi_connect/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gattc_multi_connect.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gatt_multi_connect)
diff --git a/examples/ethernet/ethernet/CMakeLists.txt b/examples/ethernet/ethernet/CMakeLists.txt
new file mode 100644
index 000000000..0b4d20f08
--- /dev/null
+++ b/examples/ethernet/ethernet/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ethernet_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ethernet_demo)
diff --git a/examples/get-started/hello_world/CMakeLists.txt b/examples/get-started/hello_world/CMakeLists.txt
index cd8c56e58..1d4853e77 100644
--- a/examples/get-started/hello_world/CMakeLists.txt
+++ b/examples/get-started/hello_world/CMakeLists.txt
@@ -1,4 +1,4 @@
-# The following five lines of boilerplate have to be in your project's
+# The following lines of boilerplate have to be in your project's
 # CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
diff --git a/examples/peripherals/adc/CMakeLists.txt b/examples/peripherals/adc/CMakeLists.txt
new file mode 100644
index 000000000..2232b277c
--- /dev/null
+++ b/examples/peripherals/adc/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/adc1_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(adc)
diff --git a/examples/peripherals/adc2/CMakeLists.txt b/examples/peripherals/adc2/CMakeLists.txt
new file mode 100644
index 000000000..650e3100a
--- /dev/null
+++ b/examples/peripherals/adc2/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/adc2_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(adc2)
diff --git a/examples/peripherals/gpio/CMakeLists.txt b/examples/peripherals/gpio/CMakeLists.txt
new file mode 100644
index 000000000..82873edc4
--- /dev/null
+++ b/examples/peripherals/gpio/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gpio_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gpio)
diff --git a/examples/peripherals/i2c/CMakeLists.txt b/examples/peripherals/i2c/CMakeLists.txt
new file mode 100644
index 000000000..048d75fb3
--- /dev/null
+++ b/examples/peripherals/i2c/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/i2c_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(i2c)
diff --git a/examples/peripherals/i2s/CMakeLists.txt b/examples/peripherals/i2s/CMakeLists.txt
new file mode 100644
index 000000000..6520061d4
--- /dev/null
+++ b/examples/peripherals/i2s/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/i2s_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(esp32-i2s-driver-example)
diff --git a/examples/peripherals/i2s_adc_dac/CMakeLists.txt b/examples/peripherals/i2s_adc_dac/CMakeLists.txt
new file mode 100644
index 000000000..8e7fe3c07
--- /dev/null
+++ b/examples/peripherals/i2s_adc_dac/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/app_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(i2s-adc-dac)
diff --git a/examples/peripherals/ledc/CMakeLists.txt b/examples/peripherals/ledc/CMakeLists.txt
new file mode 100644
index 000000000..c0c15b6f9
--- /dev/null
+++ b/examples/peripherals/ledc/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ledc_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ledc)
diff --git a/examples/peripherals/pcnt/CMakeLists.txt b/examples/peripherals/pcnt/CMakeLists.txt
new file mode 100644
index 000000000..2a7c8f40e
--- /dev/null
+++ b/examples/peripherals/pcnt/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/pcnt_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(pcnt)
diff --git a/examples/peripherals/rmt_nec_tx_rx/CMakeLists.txt b/examples/peripherals/rmt_nec_tx_rx/CMakeLists.txt
new file mode 100644
index 000000000..468032294
--- /dev/null
+++ b/examples/peripherals/rmt_nec_tx_rx/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/infrared_nec_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(infrared_nec)
diff --git a/examples/peripherals/rmt_tx/CMakeLists.txt b/examples/peripherals/rmt_tx/CMakeLists.txt
new file mode 100644
index 000000000..7aa64fedb
--- /dev/null
+++ b/examples/peripherals/rmt_tx/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/rmt_tx_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(rmt_tx)
diff --git a/examples/peripherals/sigmadelta/CMakeLists.txt b/examples/peripherals/sigmadelta/CMakeLists.txt
new file mode 100644
index 000000000..3f4df2cfc
--- /dev/null
+++ b/examples/peripherals/sigmadelta/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/sigmadelta_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sigmadelta)
diff --git a/examples/peripherals/spi_master/CMakeLists.txt b/examples/peripherals/spi_master/CMakeLists.txt
new file mode 100644
index 000000000..e7640d84f
--- /dev/null
+++ b/examples/peripherals/spi_master/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/spi_master_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spi_master)
diff --git a/examples/peripherals/timer_group/CMakeLists.txt b/examples/peripherals/timer_group/CMakeLists.txt
new file mode 100644
index 000000000..7f851e164
--- /dev/null
+++ b/examples/peripherals/timer_group/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/timer_group_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(timer_group)
diff --git a/examples/peripherals/touch_pad_interrupt/CMakeLists.txt b/examples/peripherals/touch_pad_interrupt/CMakeLists.txt
new file mode 100644
index 000000000..efdecaba1
--- /dev/null
+++ b/examples/peripherals/touch_pad_interrupt/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/tp_interrupt_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(touch_pad_interrupt)
diff --git a/examples/peripherals/touch_pad_read/CMakeLists.txt b/examples/peripherals/touch_pad_read/CMakeLists.txt
new file mode 100644
index 000000000..f246a1ad5
--- /dev/null
+++ b/examples/peripherals/touch_pad_read/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/tp_read_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(touch_pad_read)
diff --git a/examples/peripherals/uart_async_rxtxtasks/CMakeLists.txt b/examples/peripherals/uart_async_rxtxtasks/CMakeLists.txt
new file mode 100644
index 000000000..4ab23a834
--- /dev/null
+++ b/examples/peripherals/uart_async_rxtxtasks/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/uart_async_rxtxtasks_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(uart_async_rxtxtasks)
diff --git a/examples/peripherals/uart_echo/CMakeLists.txt b/examples/peripherals/uart_echo/CMakeLists.txt
new file mode 100644
index 000000000..b7ab8a582
--- /dev/null
+++ b/examples/peripherals/uart_echo/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/uart_echo_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(uart_echo)
diff --git a/examples/peripherals/uart_events/CMakeLists.txt b/examples/peripherals/uart_events/CMakeLists.txt
new file mode 100644
index 000000000..464886f25
--- /dev/null
+++ b/examples/peripherals/uart_events/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/uart_events_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(uart_events)
diff --git a/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
index 297e7b73a..c7cfd88f4 100644
--- a/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
+++ b/examples/protocols/aws_iot/subscribe_publish/CMakeLists.txt
@@ -1,13 +1,11 @@
 # The following four lines of boilerplate have to be in your project's CMakeLists
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
-set(CMAKE_TOOLCHAIN_FILE $ENV{IDF_PATH}/toolchain.cmake)
-
-project(subscribe_publish ASM C CXX)
 
 set(MAIN_SRCS main/subscribe_publish_sample.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(subscribe_publish)
 
 # Embed the certificate data directly in the built binary
 target_add_binary_data(subscribe_publish.elf main/certs/aws-root-ca.pem TEXT)
diff --git a/examples/protocols/aws_iot/thing_shadow/CMakeLists.txt b/examples/protocols/aws_iot/thing_shadow/CMakeLists.txt
new file mode 100644
index 000000000..37d5d9a9c
--- /dev/null
+++ b/examples/protocols/aws_iot/thing_shadow/CMakeLists.txt
@@ -0,0 +1,13 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/thing_shadow_sample.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(thing_shadow)
+
+# Embed the certificate data directly in the built binary
+target_add_binary_data(thing_shadow.elf main/certs/aws-root-ca.pem TEXT)
+target_add_binary_data(thing_shadow.elf main/certs/certificate.pem.crt TEXT)
+target_add_binary_data(thing_shadow.elf main/certs/private.pem.key TEXT)
diff --git a/examples/protocols/coap_client/CMakeLists.txt b/examples/protocols/coap_client/CMakeLists.txt
new file mode 100644
index 000000000..43378b8b6
--- /dev/null
+++ b/examples/protocols/coap_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/coap_client_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(coap_client)
diff --git a/examples/protocols/coap_server/CMakeLists.txt b/examples/protocols/coap_server/CMakeLists.txt
new file mode 100644
index 000000000..8495b8578
--- /dev/null
+++ b/examples/protocols/coap_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/coap_server_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(coap_server)
diff --git a/examples/protocols/http2_request/CMakeLists.txt b/examples/protocols/http2_request/CMakeLists.txt
new file mode 100644
index 000000000..b49128d5e
--- /dev/null
+++ b/examples/protocols/http2_request/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/http2_request_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(http2-request)
diff --git a/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt b/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
new file mode 100644
index 000000000..74bb26787
--- /dev/null
+++ b/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS .)
+
+set(COMPONENT_SRCDIRS .)
+
+register_component()
diff --git a/examples/protocols/http_request/CMakeLists.txt b/examples/protocols/http_request/CMakeLists.txt
new file mode 100644
index 000000000..a8f1470b9
--- /dev/null
+++ b/examples/protocols/http_request/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/http_request_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(http-request)
diff --git a/examples/protocols/https_request/CMakeLists.txt b/examples/protocols/https_request/CMakeLists.txt
new file mode 100644
index 000000000..22118c45c
--- /dev/null
+++ b/examples/protocols/https_request/CMakeLists.txt
@@ -0,0 +1,14 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/https_request_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(https_request)
+
+# Embed the server root certificate into the final binary
+#
+# (If this was a component, we would set COMPONENT_EMBED_TXTFILES here.)
+target_add_binary_data(https_request.elf
+    "main/server_root_cert.pem" TEXT)
diff --git a/examples/protocols/mdns/CMakeLists.txt b/examples/protocols/mdns/CMakeLists.txt
new file mode 100644
index 000000000..57c5e9a2e
--- /dev/null
+++ b/examples/protocols/mdns/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/mdns_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mdns-test)
diff --git a/examples/protocols/openssl_client/CMakeLists.txt b/examples/protocols/openssl_client/CMakeLists.txt
new file mode 100644
index 000000000..0fc241ddf
--- /dev/null
+++ b/examples/protocols/openssl_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/openssl_client_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(openssl_client)
diff --git a/examples/protocols/openssl_server/CMakeLists.txt b/examples/protocols/openssl_server/CMakeLists.txt
new file mode 100644
index 000000000..dba98fc68
--- /dev/null
+++ b/examples/protocols/openssl_server/CMakeLists.txt
@@ -0,0 +1,12 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/openssl_server_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(openssl_server)
+
+# Embed the certificate & key data directly in the built binary
+target_add_binary_data(openssl_server.elf main/cacert.pem TEXT)
+target_add_binary_data(openssl_server.elf main/prvtkey.pem TEXT)
diff --git a/examples/protocols/pppos_client/CMakeLists.txt b/examples/protocols/pppos_client/CMakeLists.txt
new file mode 100644
index 000000000..c9378d72f
--- /dev/null
+++ b/examples/protocols/pppos_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/pppos_client_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(pppos_client)
diff --git a/examples/protocols/sntp/CMakeLists.txt b/examples/protocols/sntp/CMakeLists.txt
new file mode 100644
index 000000000..d083f8fe1
--- /dev/null
+++ b/examples/protocols/sntp/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/sntp_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sntp)
diff --git a/examples/protocols/udp_multicast/CMakeLists.txt b/examples/protocols/udp_multicast/CMakeLists.txt
new file mode 100644
index 000000000..998524292
--- /dev/null
+++ b/examples/protocols/udp_multicast/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/udp_multicast_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(udp-multicast)
diff --git a/examples/storage/nvs_rw_blob/CMakeLists.txt b/examples/storage/nvs_rw_blob/CMakeLists.txt
new file mode 100644
index 000000000..1dd6023f3
--- /dev/null
+++ b/examples/storage/nvs_rw_blob/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/nvs_blob_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(nvs-rw-blob)
diff --git a/examples/storage/nvs_rw_value/CMakeLists.txt b/examples/storage/nvs_rw_value/CMakeLists.txt
new file mode 100644
index 000000000..971a306ef
--- /dev/null
+++ b/examples/storage/nvs_rw_value/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/nvs_value_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(nvs-rw-value)
diff --git a/examples/storage/sd_card/CMakeLists.txt b/examples/storage/sd_card/CMakeLists.txt
new file mode 100644
index 000000000..ab4bcf2fa
--- /dev/null
+++ b/examples/storage/sd_card/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/sd_card_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sd_card)
diff --git a/examples/storage/spiffs/CMakeLists.txt b/examples/storage/spiffs/CMakeLists.txt
new file mode 100644
index 000000000..0356e25bf
--- /dev/null
+++ b/examples/storage/spiffs/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/spiffs_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spiffs)
diff --git a/examples/storage/wear_levelling/CMakeLists.txt b/examples/storage/wear_levelling/CMakeLists.txt
new file mode 100644
index 000000000..bd35e0843
--- /dev/null
+++ b/examples/storage/wear_levelling/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/wear_levelling_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(wear_levelling_example)
diff --git a/examples/system/app_trace_to_host/CMakeLists.txt b/examples/system/app_trace_to_host/CMakeLists.txt
new file mode 100644
index 000000000..f26a0fdb6
--- /dev/null
+++ b/examples/system/app_trace_to_host/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/app_trace_to_host_test.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(app_trace_to_host_test)
diff --git a/examples/system/base_mac_address/CMakeLists.txt b/examples/system/base_mac_address/CMakeLists.txt
new file mode 100644
index 000000000..984dbb978
--- /dev/null
+++ b/examples/system/base_mac_address/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/base_mac_address_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(base_mac_address)
diff --git a/examples/system/console/CMakeLists.txt b/examples/system/console/CMakeLists.txt
new file mode 100644
index 000000000..416fc704a
--- /dev/null
+++ b/examples/system/console/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/cmd_wifi.c main/console_example_main.c main/cmd_system.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(console)
diff --git a/examples/system/deep_sleep/CMakeLists.txt b/examples/system/deep_sleep/CMakeLists.txt
new file mode 100644
index 000000000..cf3d195aa
--- /dev/null
+++ b/examples/system/deep_sleep/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/deep_sleep_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(deep_sleep)
diff --git a/examples/system/gcov/CMakeLists.txt b/examples/system/gcov/CMakeLists.txt
new file mode 100644
index 000000000..b1cb9fd77
--- /dev/null
+++ b/examples/system/gcov/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/gcov_example_func.c main/gcov_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(gcov_example)
diff --git a/examples/system/ota/CMakeLists.txt b/examples/system/ota/CMakeLists.txt
new file mode 100644
index 000000000..0b66883d1
--- /dev/null
+++ b/examples/system/ota/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ota_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(ota)
diff --git a/examples/system/task_watchdog/CMakeLists.txt b/examples/system/task_watchdog/CMakeLists.txt
new file mode 100644
index 000000000..e0f24b03f
--- /dev/null
+++ b/examples/system/task_watchdog/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/task_watchdog_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(task_watchdog)
diff --git a/examples/wifi/espnow/CMakeLists.txt b/examples/wifi/espnow/CMakeLists.txt
new file mode 100644
index 000000000..446cf5ccf
--- /dev/null
+++ b/examples/wifi/espnow/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/espnow_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(espnow_example)
diff --git a/examples/wifi/iperf/CMakeLists.txt b/examples/wifi/iperf/CMakeLists.txt
new file mode 100644
index 000000000..7463023e9
--- /dev/null
+++ b/examples/wifi/iperf/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/cmd_wifi.c main/main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(iperf)
diff --git a/examples/wifi/iperf/components/CMakeLists.txt b/examples/wifi/iperf/components/CMakeLists.txt
new file mode 100644
index 000000000..74bb26787
--- /dev/null
+++ b/examples/wifi/iperf/components/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_ADD_INCLUDEDIRS .)
+
+set(COMPONENT_SRCDIRS .)
+
+register_component()
diff --git a/examples/wifi/power_save/CMakeLists.txt b/examples/wifi/power_save/CMakeLists.txt
new file mode 100644
index 000000000..65cc2011d
--- /dev/null
+++ b/examples/wifi/power_save/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/power_save.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(power_save)
diff --git a/examples/wifi/scan/CMakeLists.txt b/examples/wifi/scan/CMakeLists.txt
new file mode 100644
index 000000000..9de12341a
--- /dev/null
+++ b/examples/wifi/scan/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/scan.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(scan)
diff --git a/examples/wifi/smart_config/CMakeLists.txt b/examples/wifi/smart_config/CMakeLists.txt
new file mode 100644
index 000000000..ae0b88ee6
--- /dev/null
+++ b/examples/wifi/smart_config/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/smartconfig_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(smart_config)
diff --git a/examples/wifi/wpa2_enterprise/CMakeLists.txt b/examples/wifi/wpa2_enterprise/CMakeLists.txt
new file mode 100644
index 000000000..a489894e3
--- /dev/null
+++ b/examples/wifi/wpa2_enterprise/CMakeLists.txt
@@ -0,0 +1,17 @@
+
+# (Automatically converted from project Makefile by convert_to_cmake.py.)
+
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/wpa2_enterprise_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(wpa2-enterprise)
+
+# Embed CA, certificate & key directly into binary
+target_add_binary_data(wpa2-enterprise.elf main/wpa2_ca.pem TEXT)
+target_add_binary_data(wpa2-enterprise.elf main/wpa2_client.crt TEXT)
+target_add_binary_data(wpa2-enterprise.elf main/wpa2_client.key TEXT)
+
diff --git a/examples/wifi/wps/CMakeLists.txt b/examples/wifi/wps/CMakeLists.txt
new file mode 100644
index 000000000..fd23de9aa
--- /dev/null
+++ b/examples/wifi/wps/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/wps.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(wps_example)

From 6bdc49b6e4fa8f94e3180d67575d5785d13632dd Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 16 Mar 2018 11:58:52 +1100
Subject: [PATCH 037/112] cmake: set CCACHE_BASEDIR & CCACHE_NOHASHDIR when
 using ccache

Dramatically improves build performance when building multiple
projects in different directories.
---
 tools/cmake/idf_functions.cmake | 10 ++++++----
 tools/idf.py                    | 29 +++++++++++++++++++++++------
 2 files changed, 29 insertions(+), 10 deletions(-)

diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index b679b98d3..5ed4f3f88 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -98,10 +98,12 @@ function(idf_set_global_compiler_options)
     add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
     # Enable ccache if it's on the path
-    find_program(CCACHE_FOUND ccache)
-    if(CCACHE_FOUND)
-        message(STATUS "ccache will be used")
-        set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
+	if(NOT CCACHE_DISABLE)
+		find_program(CCACHE_FOUND ccache)
+		if(CCACHE_FOUND)
+			message(STATUS "ccache will be used for faster builds")			
+			set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)		
+		endif()
     endif()
 
 endfunction()
diff --git a/tools/idf.py b/tools/idf.py
index dbffc2773..9064a8178 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -56,11 +56,12 @@ else:
     MAKE_GENERATOR = "Unix Makefiles"
 
 GENERATORS = [
-    # ('generator name', 'build command line', 'version command line')
-    ("Ninja", [ "ninja" ], [ "ninja", "--version" ]),
-    (MAKE_GENERATOR, [ MAKE_CMD, "-j", str(multiprocessing.cpu_count()+2) ], [ "make", "--version" ]),
+    # ('generator name', 'build command line', 'version command line', 'verbose flag')
+    ("Ninja", [ "ninja" ], [ "ninja", "--version" ], "-v"),
+    (MAKE_GENERATOR, [ MAKE_CMD, "-j", str(multiprocessing.cpu_count()+2) ], [ "make", "--version" ], "VERBOSE=1"),
     ]
 GENERATOR_CMDS = dict( (a[0], a[1]) for a in GENERATORS )
+GENERATOR_VERBOSE = dict( (a[0], a[3]) for a in GENERATORS )
 
 def _run_tool(tool_name, args, cwd):
     def quote_arg(arg):
@@ -107,7 +108,7 @@ def detect_cmake_generator():
     """
     Find the default cmake generator, if none was specified. Raises an exception if no valid generator is found.
     """
-    for (generator, _, version_check) in GENERATORS:
+    for (generator, _, version_check, _) in GENERATORS:
         if executable_exists(version_check):
             return generator
     raise FatalError("To use idf.py, either the 'ninja' or 'GNU make' build tool must be available in the PATH")
@@ -144,6 +145,8 @@ def _ensure_build_directory(args, always_run_cmake=False):
             cmake_args = ["cmake", "-G", args.generator]
             if not args.no_warnings:
                 cmake_args += [ "--warn-uninitialized" ]
+            if args.no_ccache:
+                cmake_args += [ "-DCCACHE_DISABLE=1" ]
             cmake_args += [ project_dir]
             _run_tool("cmake", cmake_args, cwd=args.build_dir)
         except:
@@ -167,7 +170,7 @@ def _ensure_build_directory(args, always_run_cmake=False):
 
     try:
         home_dir = cache["CMAKE_HOME_DIRECTORY"]
-        if os.path.realpath(home_dir) != os.path.realpath(project_dir):
+        if os.path.normcase(os.path.realpath(home_dir)) != os.path.normcase(os.path.realpath(project_dir)):
             raise FatalError("Build directory '%s' configured for project '%s' not '%s'. Run 'idf.py fullclean' to start again."
                             % (build_dir, os.path.realpath(home_dir), os.path.realpath(project_dir)))
     except KeyError:
@@ -201,6 +204,18 @@ def build_target(target_name, args):
     """
     _ensure_build_directory(args)
     generator_cmd = GENERATOR_CMDS[args.generator]
+    if not args.no_ccache:
+        # Setting CCACHE_BASEDIR & CCACHE_NO_HASHDIR ensures that project paths aren't stored in the ccache entries
+        # (this means ccache hits can be shared between different projects. It may mean that some debug information
+        # will point to files in another project, if these files are perfect duplicates of each other.)
+        #
+        # It would be nicer to set these from cmake, but there's no cross-platform way to set build-time environment
+        #os.environ["CCACHE_BASEDIR"] = args.build_dir
+        #os.environ["CCACHE_NO_HASHDIR"] = "1"
+        pass
+    if args.verbose:
+        generator_cmd += [ GENERATOR_VERBOSE[args.generator] ]
+
     _run_tool(generator_cmd[0], generator_cmd + [target_name], args.build_dir)
 
 
@@ -319,7 +334,9 @@ def main():
     parser.add_argument('-C', '--project-dir', help="Project directory", default=os.getcwd())
     parser.add_argument('-B', '--build-dir', help="Build directory", default=None)
     parser.add_argument('-G', '--generator', help="Cmake generator", choices=GENERATOR_CMDS.keys())
-    parser.add_argument('-n', '--no-warnings', help="Disable Cmake warnings")
+    parser.add_argument('-n', '--no-warnings', help="Disable Cmake warnings", action="store_true")
+    parser.add_argument('-v', '--verbose', help="Verbose build output", action="store_true")
+    parser.add_argument('--no-ccache', help="Disable ccache. Otherwise, if ccache is available on the PATH then it will be used for faster builds.", action="store_true")
     parser.add_argument('actions', help="Actions (build targets or other operations)", nargs='+',
                         choices=ACTIONS.keys())
 

From 2ea359ad0ca8b22401c87a4c6852674a78b7f121 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 19 Mar 2018 14:17:31 +1100
Subject: [PATCH 038/112] cmake: Cleanups to work with Windows

---
 tools/cmake/idf_functions.cmake | 3 +--
 tools/cmake/project.cmake       | 5 +++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 5ed4f3f88..923478231 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -18,8 +18,7 @@ macro(idf_set_global_variables)
     # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
     set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
 
-    # Note: "main" is no longer a component...
-    #
+    # Note: Unlike older build system, "main" is no longer a component. See build docs for details.    
     set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
     spaces2list(COMPONENT_DIRS)
 
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index ef5f6740d..b9fe126b9 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -7,9 +7,10 @@ set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
     # Documentation says you should set IDF_PATH in your environment, but we
     # can infer it here if it's not set.
-    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
-    set($ENV{IDF_PATH} "${IDF_PATH}")
+    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})    
 endif()
+file(TO_CMAKE_PATH "${IDF_PATH}" IDF_PATH)
+set($ENV{IDF_PATH} "${IDF_PATH}")
 
 #
 # Load cmake modules

From b44c8b125f67bcdcfc639ff76c8d3e1cdf586ed6 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 20 Mar 2018 12:27:00 +1100
Subject: [PATCH 039/112] cmake: Style cleanup, add cmake linter to gitlab CI

---
 .gitlab-ci.yml                            |  6 ++++++
 components/app_trace/CMakeLists.txt       |  2 +-
 components/bt/CMakeLists.txt              |  4 ++--
 tools/cmake/crosstool_version_check.cmake |  8 ++++----
 tools/cmake/idf_functions.cmake           | 14 +++++++-------
 tools/cmake/project.cmake                 |  2 +-
 6 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a0e579ea1..d18cfa8a3 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -234,6 +234,12 @@ build_docs:
     - make html
     - ../check_doc_warnings.sh
 
+verify_cmake_style:
+  stage: build
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
+  script:
+    tools/cmake/run_cmake_lint.sh
+
 test_nvs_on_host:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
diff --git a/components/app_trace/CMakeLists.txt b/components/app_trace/CMakeLists.txt
index ebdfd941c..fec9b921d 100644
--- a/components/app_trace/CMakeLists.txt
+++ b/components/app_trace/CMakeLists.txt
@@ -1,7 +1,7 @@
 set(COMPONENT_SRCDIRS "." "gcov")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
-if (CONFIG_SYSVIEW_ENABLE)
+if(CONFIG_SYSVIEW_ENABLE)
     list(APPEND COMPONENT_ADD_INCLUDEDIRS
         sys_view/Config
         sys_view/SEGGER
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index f802be0f1..9431645e8 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -15,7 +15,7 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/hci/include
         bluedroid/osi/include
         bluedroid/external/sbc/decoder/include
-		bluedroid/external/sbc/encoder/include
+        bluedroid/external/sbc/encoder/include
         bluedroid/btc/profile/esp/blufi/include
         bluedroid/btc/profile/esp/include
         bluedroid/btc/profile/std/a2dp/include
@@ -51,7 +51,7 @@ if(CONFIG_BLUEDROID_ENABLED)
         bluedroid/main
         bluedroid/osi
         bluedroid/external/sbc/decoder/srce
-	    bluedroid/external/sbc/encoder/srce
+        bluedroid/external/sbc/encoder/srce
         bluedroid/btc/core
         bluedroid/btc/profile/esp/blufi
         bluedroid/btc/profile/std/gap
diff --git a/tools/cmake/crosstool_version_check.cmake b/tools/cmake/crosstool_version_check.cmake
index f55f121d3..d572a82a7 100644
--- a/tools/cmake/crosstool_version_check.cmake
+++ b/tools/cmake/crosstool_version_check.cmake
@@ -18,10 +18,10 @@ function(crosstool_version_check expected_ctng_version)
 
     string(REGEX MATCH "crosstool-ng-[0-9a-g\\.-]+" ctng_version "${toolchain_stderr}")
     string(REPLACE "crosstool-ng-" "" ctng_version "${ctng_version}")
-	# We use FIND to match version instead of STREQUAL because some toolchains are built
-	# with longer git hash strings than others. This will match any version which starts with
-	# the expected version string.
-	string(FIND "${ctng_version}" "${expected_ctng_version}" found_expected_version)
+    # We use FIND to match version instead of STREQUAL because some toolchains are built
+    # with longer git hash strings than others. This will match any version which starts with
+    # the expected version string.
+    string(FIND "${ctng_version}" "${expected_ctng_version}" found_expected_version)
     if(NOT ctng_version)
         message(WARNING "Xtensa toolchain ${CMAKE_C_COMPILER} does not appear to be built with crosstool-ng. "
             "${ctng_version_warning}")
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 923478231..e88e980af 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -18,7 +18,7 @@ macro(idf_set_global_variables)
     # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
     set(PROJECT_PATH "${CMAKE_SOURCE_DIR}")
 
-    # Note: Unlike older build system, "main" is no longer a component. See build docs for details.    
+    # Note: Unlike older build system, "main" is no longer a component. See build docs for details.
     set_default(COMPONENT_DIRS "${PROJECT_PATH}/components ${EXTRA_COMPONENT_DIRS} ${IDF_PATH}/components")
     spaces2list(COMPONENT_DIRS)
 
@@ -97,12 +97,12 @@ function(idf_set_global_compiler_options)
     add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
 
     # Enable ccache if it's on the path
-	if(NOT CCACHE_DISABLE)
-		find_program(CCACHE_FOUND ccache)
-		if(CCACHE_FOUND)
-			message(STATUS "ccache will be used for faster builds")			
-			set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)		
-		endif()
+    if(NOT CCACHE_DISABLE)
+        find_program(CCACHE_FOUND ccache)
+        if(CCACHE_FOUND)
+            message(STATUS "ccache will be used for faster builds")
+            set_property(GLOBAL PROPERTY RULE_LAUNCH_COMPILE ccache)
+        endif()
     endif()
 
 endfunction()
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index b9fe126b9..115963c56 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -7,7 +7,7 @@ set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
     # Documentation says you should set IDF_PATH in your environment, but we
     # can infer it here if it's not set.
-    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})    
+    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
 endif()
 file(TO_CMAKE_PATH "${IDF_PATH}" IDF_PATH)
 set($ENV{IDF_PATH} "${IDF_PATH}")

From 2a3e2b8eed79c2f755c7e57e97199792d72d3c18 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 20 Mar 2018 16:31:53 +1100
Subject: [PATCH 040/112] doc: Use confgen.py to build docs from same code path
 as config generation

---
 docs/conf_common.py                  |  18 +++-
 docs/gen-kconfig-doc.py              | 120 ---------------------------
 tools/kconfig_new/gen_kconfig_doc.py |  28 +++++--
 3 files changed, 34 insertions(+), 132 deletions(-)
 delete mode 100755 docs/gen-kconfig-doc.py

diff --git a/docs/conf_common.py b/docs/conf_common.py
index e5dd9df6e..16efc9d3c 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -16,7 +16,7 @@
 
 import sys, os
 import re
-from subprocess import Popen, PIPE
+import subprocess
 import shlex
 
 # Note: If extensions (or modules to document with autodoc) are in another directory,
@@ -41,9 +41,21 @@ copy_if_modified('xml/', 'xml_in/')
 os.system('python ../gen-dxd.py')
 
 # Generate 'kconfig.inc' file from components' Kconfig files
+print "Generating kconfig.inc from kconfig contents"
 kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
-os.system('python ../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
-copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
+temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
+kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"])
+kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"])
+confgen_args = ["python",
+                "../../tools/kconfig_new/confgen.py",
+                "--kconfig", "../../Kconfig",
+                "--config", temp_sdkconfig_path,
+                "--create-config-if-missing",
+                "--env", "COMPONENT_KCONFIGS={}".format(kconfigs),
+                "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(kconfig_projbuilds),
+                "--output", "docs", kconfig_inc_path
+]
+subprocess.check_call(confgen_args)
 
 # http://stackoverflow.com/questions/12772927/specifying-an-online-image-in-sphinx-restructuredtext-format
 # 
diff --git a/docs/gen-kconfig-doc.py b/docs/gen-kconfig-doc.py
deleted file mode 100755
index a14164119..000000000
--- a/docs/gen-kconfig-doc.py
+++ /dev/null
@@ -1,120 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
-#
-# gen-kconfig-doc.py — generate Sphinx .rst file from Kconfig files
-#
-# This script iterates over Kconfig and Kconfig.projbuild files in
-# ESP-IDF component directories, and outputs documentation for these options
-# as ReST markup.
-# For each option in Kconfig file (e.g. 'FOO'), CONFIG_FOO link target is
-# generated, allowing options to be referenced in other documents 
-# (using :ref:`CONFIG_FOO`)
-#
-# This script uses kconfiglib library to do all the work of parsing Kconfig
-# files: https://github.com/ulfalizer/Kconfiglib
-#
-# Copyright 2017 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 = 2
-MAX_HEADING_LEVEL = 5
-OPTION_HEADING_LEVEL = 6
-
-
-def print_menu_contents(title, items, heading_level, breadcrumbs):
-    if title:
-        print_section_heading(title, heading_level)
-    for entry in items:
-        if entry.is_menu():
-            if len(breadcrumbs) > 0:
-                new_breadcrumbs = breadcrumbs + ' > ' + entry.get_title()
-            else:
-                new_breadcrumbs = entry.get_title()
-
-            print_menu_contents(entry.get_title(), entry.get_items(),
-                                min(heading_level + 1, MAX_HEADING_LEVEL),
-                                new_breadcrumbs)
-        elif entry.is_choice():
-            print_choice(entry, breadcrumbs)
-        else:
-            if len(entry.get_prompts()) == 0:
-                # Skip entries which can never be visible
-                continue
-            # Currently this does not handle 'menuconfig' entires in any special way,
-            # as Kconfglib offers no way of recognizing them automatically.
-            print_option(entry, breadcrumbs)
-        # Trailing newline after every option
-        print
-
-def print_choice(choice, breadcrumbs):
-    print_option(choice, breadcrumbs)
-    print
-    print '%sAvailable options:' % INDENT
-    for opt in choice.get_symbols():
-        # Format available options as a list
-        print '%s- %s' % (INDENT * 2, opt.name)
-
-def print_section_heading(title, heading_level):
-    print title
-    print HEADING_SYMBOLS[heading_level] * len(title)
-    print
-
-def print_option(opt, breadcrumbs):
-    # add link target so we can use :ref:`CONFIG_FOO` 
-    print '.. _CONFIG_%s:' % opt.name
-    print
-    print_section_heading(opt.name, OPTION_HEADING_LEVEL)
-    if len(opt.prompts) > 0:
-        print '%s%s' % (INDENT, opt.prompts[0][0])
-        print
-    print '%s:emphasis:`Found in: %s`' % (INDENT, breadcrumbs)
-    print
-    if opt.get_help() is not None:
-        # 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.
-        print '%s%s' % (INDENT, opt.get_help().replace('\n', '\n%s' % INDENT))
-
-def process_kconfig_file(kconfig_file, heading_level, breadcrumbs):
-    if os.path.exists(kconfig_file):
-        cfg = kconfiglib.Config(kconfig_file, print_warnings=True)
-        print_menu_contents(None, cfg.get_top_level_items(), heading_level, breadcrumbs)
-
-def print_all_components():
-    heading_level = INITIAL_HEADING_LEVEL
-    # Currently this works only for IDF components.
-    # TODO: figure out if this can be re-used for documenting applications?
-    components_path = os.path.join(os.path.curdir, '../..', 'components')
-    for component_name in os.listdir(components_path):
-        if component_name.startswith('.'):
-            continue    # skip system thumbnail folders
-
-        kconfig_file_path = os.path.join(components_path, component_name, 'Kconfig')
-
-        process_kconfig_file(kconfig_file_path, heading_level, 'Component config')
-        process_kconfig_file(kconfig_file_path + '.projbuild', heading_level, '')
-
-if __name__ == '__main__':
-    print_all_components()
diff --git a/tools/kconfig_new/gen_kconfig_doc.py b/tools/kconfig_new/gen_kconfig_doc.py
index 6614c54c3..e5e6968f1 100644
--- a/tools/kconfig_new/gen_kconfig_doc.py
+++ b/tools/kconfig_new/gen_kconfig_doc.py
@@ -7,7 +7,7 @@
 # generated, allowing options to be referenced in other documents
 # (using :ref:`CONFIG_FOO`)
 #
-# Copyright 2017 Espressif Systems (Shanghai) PTE LTD
+# 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.
@@ -30,12 +30,13 @@ INDENT = '    '
 HEADING_SYMBOLS = '#*=-^"+'
 
 # Keep the heading level in sync with api-reference/kconfig.rst
-INITIAL_HEADING_LEVEL = 2
-MAX_HEADING_LEVEL = 5
+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. """
+    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))
 
@@ -61,6 +62,15 @@ def get_heading_level(node):
         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
@@ -87,12 +97,12 @@ def write_menu_item(f, node):
         title = node.prompt[0]
 
     # if no symbol name, use the prompt as the heading
-    if is_menu:
+    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')
+        f.write('**%s**\n\n\n' % title)
 
     if name:
         f.write('%s%s\n\n' % (INDENT, node.prompt[0]))
@@ -103,7 +113,7 @@ def write_menu_item(f, node):
             # 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('%s%s\n' % (INDENT, node.help.replace('\n', '\n%s' % INDENT)))
+            f.write(format_rest_text(node.help, INDENT))
     except AttributeError:
         pass  # No help
 
@@ -115,8 +125,8 @@ def write_menu_item(f, node):
             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 = choice_node.help.replace('\n', '\n%s  ' % HELP_INDENT)
-                f.write('%s  \n%s  %s\n' % (HELP_INDENT, HELP_INDENT, fmt_help))
+                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')

From f1d3bfc0c7f2715336e50034ac4c10f955966f2e Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 5 Apr 2018 17:13:53 +1000
Subject: [PATCH 041/112] cmake: Add new flasher_args.json file for IDE
 parsing, document metadata files better

---
 components/esptool_py/CMakeLists.txt       |  5 +++++
 components/esptool_py/flasher_args.json.in | 11 +++++++++++
 docs/en/api-guides/build-system-cmake.rst  | 10 +++++++++-
 tools/cmake/project_description.json.in    |  6 ------
 4 files changed, 25 insertions(+), 7 deletions(-)
 create mode 100644 components/esptool_py/flasher_args.json.in

diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
index 5a7d23efd..0d62557c8 100644
--- a/components/esptool_py/CMakeLists.txt
+++ b/components/esptool_py/CMakeLists.txt
@@ -7,3 +7,8 @@ foreach(part project app bootloader)
         "${CMAKE_BINARY_DIR}/flash_${part}_args"
         )
 endforeach()
+
+configure_file(
+    "${CMAKE_CURRENT_LIST_DIR}/flasher_args.json.in"
+    "${CMAKE_BINARY_DIR}/flasher_args.json"
+    )
diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
new file mode 100644
index 000000000..0266316ea
--- /dev/null
+++ b/components/esptool_py/flasher_args.json.in
@@ -0,0 +1,11 @@
+{
+    "write_flash_args" : [ "--flash_mode", "${ESPFLASHMODE}",
+                           "--flash_size", "${ESPFLASHSIZE}",
+                           "--flash_freq", "${ESPFLASHFREQ}" ],
+    "flash_files" : {
+        "0x1000" : "bootloader/bootloader.bin",
+        "0x8000" : "partition_table/partition-table.bin",
+        "${CONFIG_APP_OFFSET}" : "${PROJECT_NAME}.bin",
+        "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}"
+    }
+}
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index c363058c6..a4de84060 100644
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -638,7 +638,7 @@ You can pass any of these flasher argument files to ``esptool.py`` as follows::
 
 Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
 
-The build directory also contains a generated file ``project_description.json`` which contains project information, including project flash information, in the JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
+The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
 
 Building the Bootloader
 =======================
@@ -727,6 +727,14 @@ The following variables no longer have default values:
 
 It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
 
+Build System Metadata
+=====================
+
+For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+
+- ``project_description.json`` contains some general information about the project, configured paths, etc.
+- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`.
+- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
 
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _cmake: https://cmake.org
diff --git a/tools/cmake/project_description.json.in b/tools/cmake/project_description.json.in
index 2fb99c149..1acffbd62 100644
--- a/tools/cmake/project_description.json.in
+++ b/tools/cmake/project_description.json.in
@@ -6,12 +6,6 @@
     "app_elf":            "${PROJECT_NAME}.elf",
     "app_bin":            "${PROJECT_NAME}.bin",
     "git_revision":       "${IDF_VER}",
-    "project_binaries":  {
-        "bootloader":        [ "0x1000", "bootloader/bootloader.bin" ],
-        "partition_table":   [ "0x8000", "partition_table/partition-table.bin" ],
-        "app":               [ "${CONFIG_APP_OFFSET}", "${PROJECT_NAME}.bin" ],
-        "phy_data":          [ "${PHY_PARTITION_OFFSET}", "${PHY_PARTITION_BIN_FILE}" ]
-    },
     "phy_data_partition": "${CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION}",
     "monitor_baud" : "${CONFIG_MONITOR_BAUD}"
 }

From 56902f00549e5fc1837d0896e91bd50a229f6834 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 5 Apr 2018 17:26:28 +1000
Subject: [PATCH 042/112] cmake: Write configuration & component metadata to
 project_description.json

---
 tools/cmake/kconfig.cmake               | 5 +++++
 tools/cmake/project.cmake               | 4 ++++
 tools/cmake/project_description.json.in | 9 ++++++++-
 tools/cmake/utilities.cmake             | 6 ++++++
 4 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 277568959..cc2156305 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -52,6 +52,11 @@ function(kconfig_process_config)
         set(defaults_arg --defaults "${SDKCONFIG_DEFAULTS}")
     endif()
 
+    # Set these in the parent scope, so that they can be written to project_description.json
+    set(kconfigs "${kconfigs}")
+    set(COMPONENT_KCONFIGS "${kconfigs}" PARENT_SCOPE)
+    set(COMPONENT_KCONFIGS_PROJBUILD "${kconfigs_projbuild}" PARENT_SCOPE)
+
     set(confgen_basecommand
         ${PYTHON} ${IDF_PATH}/tools/kconfig_new/confgen.py
         --kconfig ${ROOT_KCONFIG}
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 115963c56..26be56eda 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -108,8 +108,12 @@ macro(project name)
     idf_add_executable()
 
     # Write project description JSON file
+    make_json_list("${BUILD_COMPONENTS}" build_components_json)
+    make_json_list("${BUILD_COMPONENT_PATHS}" build_component_paths_json)
     configure_file("${IDF_PATH}/tools/cmake/project_description.json.in"
         "${CMAKE_BINARY_DIR}/project_description.json")
+    unset(build_components_json)
+    unset(build_component_paths_json)
 
     #
     # Finish component registration (add cross-dependencies, make
diff --git a/tools/cmake/project_description.json.in b/tools/cmake/project_description.json.in
index 1acffbd62..878dce3b3 100644
--- a/tools/cmake/project_description.json.in
+++ b/tools/cmake/project_description.json.in
@@ -3,9 +3,16 @@
     "project_path":       "${PROJECT_PATH}",
     "build_dir":          "${CMAKE_BINARY_DIR}",
     "config_file":        "${SDKCONFIG}",
+    "config_defaults":    "${SDKCONFIG_DEFAULTS}",
     "app_elf":            "${PROJECT_NAME}.elf",
     "app_bin":            "${PROJECT_NAME}.bin",
     "git_revision":       "${IDF_VER}",
     "phy_data_partition": "${CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION}",
-    "monitor_baud" : "${CONFIG_MONITOR_BAUD}"
+    "monitor_baud" : "${CONFIG_MONITOR_BAUD}",
+    "config_environment" : {
+        "COMPONENT_KCONFIGS" : "${COMPONENT_KCONFIGS}",
+        "COMPONENT_KCONFIGS_PROJBUILD" : "${COMPONENT_KCONFIGS_PROJBUILD}"
+    },
+    "build_components" : ${build_components_json},
+    "build_component_paths" : ${build_component_paths_json}
 }
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index f3c0c1981..e91385180 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -170,3 +170,9 @@ function(target_linker_script target scriptfile)
     # executable(s) the library is linked to. This is done manually in components.cmake.
     set_property(TARGET "${target}" APPEND PROPERTY LINK_DEPENDS "${abs_script}")
 endfunction()
+
+# Convert a CMake list to a JSON list and store it in a variable
+function(make_json_list list variable)
+    string(REPLACE ";" "\", \"" result "[ \"${list}\" ]")
+    set("${variable}" "${result}" PARENT_SCOPE)
+endfunction()

From 4a2f1f03549294c08eb1f320b21f9e6febdb75e6 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 5 Apr 2018 17:32:22 +1000
Subject: [PATCH 043/112] esptool: Add note that ESPTOOLPY_PORT &
 ESPTOOLPY_BAUD are ignored when using idf.py

---
 components/esptool_py/Kconfig.projbuild | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild
index 84ca5d683..c87d8adcf 100644
--- a/components/esptool_py/Kconfig.projbuild
+++ b/components/esptool_py/Kconfig.projbuild
@@ -4,15 +4,19 @@ config ESPTOOLPY_PORT
 	string "Default serial port"
 	default "/dev/ttyUSB0"
 	help
-		The serial port that's connected to the ESP chip. This can be overridden by setting the ESPPORT
-		environment variable.
+        The serial port that's connected to the ESP chip. This can be overridden by setting the ESPPORT
+        environment variable.
+
+        This value is ignored when using the CMake-based build system or idf.py.
 
 choice ESPTOOLPY_BAUD
-	prompt "Default baud rate"
-	default ESPTOOLPY_BAUD_115200B
-	help
-		Default baud rate to use while communicating with the ESP chip. Can be overridden by
-		setting the ESPBAUD variable.
+    prompt "Default baud rate"
+    default ESPTOOLPY_BAUD_115200B
+    help
+        Default baud rate to use while communicating with the ESP chip. Can be overridden by
+        setting the ESPBAUD variable.
+
+        This value is ignored when using the CMake-based build system or idf.py.
 
 config ESPTOOLPY_BAUD_115200B
 	bool "115200 baud"

From 1cb5712463a8963cd3e8331da90fb5e03f13575f Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 22 Mar 2018 17:27:10 +1100
Subject: [PATCH 044/112] cmake: Add component dependency support

Components should set the COMPONENT_REQUIRES & COMPONENT_PRIVATE_REQUIRES variables to define their
requirements.
---
 components/app_trace/CMakeLists.txt           |   3 +
 components/app_update/CMakeLists.txt          |   3 +
 components/app_update/esp_ota_ops.c           |   1 +
 components/app_update/include/esp_ota_ops.h   |   1 -
 components/aws_iot/CMakeLists.txt             |  11 +-
 components/bootloader/CMakeLists.txt          |   7 +-
 .../bootloader/subproject/CMakeLists.txt      |   2 +
 components/bootloader_support/CMakeLists.txt  |   4 +
 components/bt/CMakeLists.txt                  | 161 ++++++-------
 components/coap/CMakeLists.txt                |   2 +
 components/console/CMakeLists.txt             |   2 +
 components/cxx/CMakeLists.txt                 |   1 +
 components/driver/CMakeLists.txt              |   2 +
 components/esp-tls/CMakeLists.txt             |   7 +
 components/esp32/CMakeLists.txt               |  11 +-
 components/esp_adc_cal/CMakeLists.txt         |   2 +
 components/ethernet/CMakeLists.txt            |   3 +
 components/expat/CMakeLists.txt               |   2 +
 components/fatfs/CMakeLists.txt               |   2 +
 components/freertos/CMakeLists.txt            |   2 +
 components/heap/CMakeLists.txt                |   2 +
 components/idf_test/CMakeLists.txt            |   1 +
 components/jsmn/CMakeLists.txt                |   2 +
 components/json/CMakeLists.txt                |   2 +
 components/libsodium/CMakeLists.txt           |   2 +
 components/log/CMakeLists.txt                 |   1 +
 components/lwip/CMakeLists.txt                |   3 +
 components/mbedtls/CMakeLists.txt             |   2 +
 components/mdns/CMakeLists.txt                |   2 +
 components/micro-ecc/CMakeLists.txt           |   2 +
 components/newlib/CMakeLists.txt              |   2 +
 components/nghttp/CMakeLists.txt              |   2 +
 components/nvs_flash/CMakeLists.txt           |   2 +
 components/openssl/CMakeLists.txt             |   2 +
 components/partition_table/CMakeLists.txt     |   3 +-
 components/pthread/CMakeLists.txt             |   1 +
 components/sdmmc/CMakeLists.txt               |   2 +-
 components/smartconfig/CMakeLists.txt         |   2 +
 components/soc/CMakeLists.txt                 |   3 +
 components/spi_flash/CMakeLists.txt           |   3 +
 components/spiffs/CMakeLists.txt              |   4 +
 components/tcpip_adapter/CMakeLists.txt       |   2 +
 components/ulp/CMakeLists.txt                 |   2 +
 components/vfs/CMakeLists.txt                 |   2 +
 components/wear_levelling/CMakeLists.txt      |   1 +
 components/wpa_supplicant/CMakeLists.txt      |   3 +
 components/xtensa-debug-module/CMakeLists.txt |   2 +
 docs/en/api-guides/build-system-cmake.rst     |  70 ++++--
 docs/en/api-guides/build-system.rst           |   4 +-
 .../components/sh2lib/CMakeLists.txt          |   3 +
 tools/cmake/components.cmake                  | 137 +++++------
 tools/cmake/convert_to_cmake.py               |   5 +
 tools/cmake/idf_functions.cmake               |   4 +
 tools/cmake/kconfig.cmake                     |   2 +-
 tools/cmake/project.cmake                     |  36 ++-
 tools/cmake/scripts/expand_requirements.cmake | 216 ++++++++++++++++++
 56 files changed, 562 insertions(+), 201 deletions(-)
 create mode 100644 components/esp-tls/CMakeLists.txt
 create mode 100644 tools/cmake/scripts/expand_requirements.cmake

diff --git a/components/app_trace/CMakeLists.txt b/components/app_trace/CMakeLists.txt
index fec9b921d..5a6f19dbb 100644
--- a/components/app_trace/CMakeLists.txt
+++ b/components/app_trace/CMakeLists.txt
@@ -14,6 +14,9 @@ if(CONFIG_SYSVIEW_ENABLE)
         "sys_view/esp32")
 endif()
 
+set(COMPONENT_REQUIRES)
+set(COMPONENT_PRIV_REQUIRES xtensa-debug-module)
+
 register_component()
 
 # disable --coverage for this component, as it is used as transport
diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt
index ba2fa9c7e..44663f68e 100644
--- a/components/app_update/CMakeLists.txt
+++ b/components/app_update/CMakeLists.txt
@@ -1,4 +1,7 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES "")
+set(COMPONENT_PRIV_REQUIRES bootloader_support spi_flash)
+
 register_component()
diff --git a/components/app_update/esp_ota_ops.c b/components/app_update/esp_ota_ops.c
index 8e26ba162..1047d2117 100644
--- a/components/app_update/esp_ota_ops.c
+++ b/components/app_update/esp_ota_ops.c
@@ -28,6 +28,7 @@
 #include "esp_image_format.h"
 #include "esp_secure_boot.h"
 #include "esp_flash_encrypt.h"
+#include "esp_spi_flash.h"
 #include "sdkconfig.h"
 
 #include "esp_ota_ops.h"
diff --git a/components/app_update/include/esp_ota_ops.h b/components/app_update/include/esp_ota_ops.h
index a089a92be..8fcf622d3 100755
--- a/components/app_update/include/esp_ota_ops.h
+++ b/components/app_update/include/esp_ota_ops.h
@@ -20,7 +20,6 @@
 #include <stddef.h>
 #include "esp_err.h"
 #include "esp_partition.h"
-#include "esp_spi_flash.h"
 
 #ifdef __cplusplus
 extern "C"
diff --git a/components/aws_iot/CMakeLists.txt b/components/aws_iot/CMakeLists.txt
index f8bfb26a2..f7644bd7a 100644
--- a/components/aws_iot/CMakeLists.txt
+++ b/components/aws_iot/CMakeLists.txt
@@ -1,8 +1,11 @@
-if(NOT CONFIG_AWS_IOT_SDK)
-    return()
+if(CONFIG_AWS_IOT_SDK)
+    set(COMPONENT_ADD_INCLUDEDIRS "include aws-iot-device-sdk-embedded-C/include")
+    set(COMPONENT_SRCDIRS "aws-iot-device-sdk-embedded-C/src port")
+else()
+    message(STATUS "Building empty aws_iot component due to configuration")
 endif()
 
-set(COMPONENT_ADD_INCLUDEDIRS "include aws-iot-device-sdk-embedded-C/include")
-set(COMPONENT_SRCDIRS "aws-iot-device-sdk-embedded-C/src port")
+set(COMPONENT_REQUIRES "mbedtls")
+set(COMPONENT_PRIV_REQUIRES "jsmn")
 
 register_component()
diff --git a/components/bootloader/CMakeLists.txt b/components/bootloader/CMakeLists.txt
index 1b694f381..d38b8ff8e 100644
--- a/components/bootloader/CMakeLists.txt
+++ b/components/bootloader/CMakeLists.txt
@@ -1,2 +1,7 @@
-# TODO: add config stuff for bootloader here
+# bootloader component logic is all in project_include.cmake,
+# and subproject/CMakeLists.txt.
+#
+# This file is only included so the build system finds the
+# component
+
 
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index 5ac887a40..719d9fb9d 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -9,6 +9,8 @@ set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash
 set(BOOTLOADER_BUILD 1)
 add_definitions(-DBOOTLOADER_BUILD=1)
 
+set(COMPONENT_REQUIRES_COMMON log esp32 soc)
+
 set(MAIN_SRCS main/bootloader_start.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
diff --git a/components/bootloader_support/CMakeLists.txt b/components/bootloader_support/CMakeLists.txt
index 6df7b24db..21978397e 100644
--- a/components/bootloader_support/CMakeLists.txt
+++ b/components/bootloader_support/CMakeLists.txt
@@ -2,9 +2,13 @@ set(COMPONENT_SRCDIRS "src")
 
 if(${BOOTLOADER_BUILD})
     set(COMPONENT_ADD_INCLUDEDIRS "include include_priv")
+    set(COMPONENT_REQUIRES)
+    set(COMPONENT_PRIV_REQUIRES spi_flash micro-ecc)
 else()
     set(COMPONENT_ADD_INCLUDEDIRS "include")
     set(COMPONENT_PRIV_INCLUDEDIRS "include_priv")
+    set(COMPONENT_REQUIRES)
+    set(COMPONENT_PRIV_REQUIRES spi_flash mbedtls micro-ecc)
 endif()
 
 register_component()
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index 9431645e8..c2134be8f 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -1,83 +1,90 @@
-if(NOT CONFIG_BT_ENABLED)
-    return()
+if(CONFIG_BT_ENABLED)
+
+    set(COMPONENT_SRCDIRS .)
+    set(COMPONENT_ADD_INCLUDEDIRS include)
+
+    if(CONFIG_BLUEDROID_ENABLED)
+
+        list(APPEND COMPONENT_ADD_INCLUDEDIRS
+            bluedroid/bta/include
+		    bluedroid/bta/sys/include
+		    bluedroid/btcore/include
+		    bluedroid/device/include
+		    bluedroid/hci/include
+		    bluedroid/osi/include
+		    bluedroid/external/sbc/decoder/include
+		    bluedroid/external/sbc/encoder/include
+		    bluedroid/btc/profile/esp/blufi/include
+		    bluedroid/btc/profile/esp/include
+		    bluedroid/btc/profile/std/a2dp/include
+		    bluedroid/btc/profile/std/include
+		    bluedroid/btc/include
+		    bluedroid/stack/gap/include
+		    bluedroid/stack/gatt/include
+		    bluedroid/stack/l2cap/include
+		    bluedroid/stack/sdp/include
+		    bluedroid/stack/smp/include
+		    bluedroid/stack/avct/include
+		    bluedroid/stack/avrc/include
+		    bluedroid/stack/avdt/include
+		    bluedroid/stack/a2dp/include
+		    bluedroid/stack/rfcomm/include
+		    bluedroid/stack/include
+		    bluedroid/api/include
+		    bluedroid/include
+            )
+
+        list(APPEND COMPONENT_SRCDIRS
+            bluedroid/bta/dm
+		    bluedroid/bta/gatt
+		    bluedroid/bta/hh
+		    bluedroid/bta/sdp
+		    bluedroid/bta/av
+		    bluedroid/bta/ar
+		    bluedroid/bta/sys
+		    bluedroid/bta/jv
+		    bluedroid/btcore
+		    bluedroid/btif
+		    bluedroid/device
+		    bluedroid/hci
+		    bluedroid/main
+		    bluedroid/osi
+		    bluedroid/external/sbc/decoder/srce
+		    bluedroid/external/sbc/encoder/srce
+		    bluedroid/btc/core
+		    bluedroid/btc/profile/esp/blufi
+		    bluedroid/btc/profile/std/gap
+		    bluedroid/btc/profile/std/gatt
+		    bluedroid/btc/profile/std/a2dp
+		    bluedroid/btc/profile/std/avrc
+		    bluedroid/btc/profile/std/spp
+		    bluedroid/stack/btm
+		    bluedroid/stack/btu
+		    bluedroid/stack/gap
+		    bluedroid/stack/gatt
+		    bluedroid/stack/hcic
+		    bluedroid/stack/l2cap
+		    bluedroid/stack/sdp
+		    bluedroid/stack/smp
+		    bluedroid/stack/avct
+		    bluedroid/stack/avrc
+		    bluedroid/stack/avdt
+		    bluedroid/stack/a2dp
+		    bluedroid/stack/rfcomm
+		    bluedroid/api
+            )
+    endif()
 endif()
 
-set(COMPONENT_SRCDIRS .)
-set(COMPONENT_ADD_INCLUDEDIRS include)
+# requirements can't depend on config
+set(COMPONENT_PRIV_REQUIRES lwip nvs_flash)
 
-if(CONFIG_BLUEDROID_ENABLED)
-
-    list(APPEND COMPONENT_ADD_INCLUDEDIRS
-        bluedroid/bta/include
-        bluedroid/bta/sys/include
-        bluedroid/btcore/include
-        bluedroid/device/include
-        bluedroid/hci/include
-        bluedroid/osi/include
-        bluedroid/external/sbc/decoder/include
-        bluedroid/external/sbc/encoder/include
-        bluedroid/btc/profile/esp/blufi/include
-        bluedroid/btc/profile/esp/include
-        bluedroid/btc/profile/std/a2dp/include
-        bluedroid/btc/profile/std/include
-        bluedroid/btc/include
-        bluedroid/stack/gap/include
-        bluedroid/stack/gatt/include
-        bluedroid/stack/l2cap/include
-        bluedroid/stack/sdp/include
-        bluedroid/stack/smp/include
-        bluedroid/stack/avct/include
-        bluedroid/stack/avrc/include
-        bluedroid/stack/avdt/include
-        bluedroid/stack/a2dp/include
-        bluedroid/stack/rfcomm/include
-        bluedroid/stack/include
-        bluedroid/api/include
-        bluedroid/include)
-
-    list(APPEND COMPONENT_SRCDIRS
-        bluedroid/bta/dm
-        bluedroid/bta/gatt
-        bluedroid/bta/hh
-        bluedroid/bta/sdp
-        bluedroid/bta/av
-        bluedroid/bta/ar
-        bluedroid/bta/sys
-        bluedroid/bta/jv
-        bluedroid/btcore
-        bluedroid/btif
-        bluedroid/device
-        bluedroid/hci
-        bluedroid/main
-        bluedroid/osi
-        bluedroid/external/sbc/decoder/srce
-        bluedroid/external/sbc/encoder/srce
-        bluedroid/btc/core
-        bluedroid/btc/profile/esp/blufi
-        bluedroid/btc/profile/std/gap
-        bluedroid/btc/profile/std/gatt
-        bluedroid/btc/profile/std/a2dp
-        bluedroid/btc/profile/std/avrc
-        bluedroid/btc/profile/std/spp
-        bluedroid/stack/btm
-        bluedroid/stack/btu
-        bluedroid/stack/gap
-        bluedroid/stack/gatt
-        bluedroid/stack/hcic
-        bluedroid/stack/l2cap
-        bluedroid/stack/sdp
-        bluedroid/stack/smp
-        bluedroid/stack/avct
-        bluedroid/stack/avrc
-        bluedroid/stack/avdt
-        bluedroid/stack/a2dp
-        bluedroid/stack/rfcomm
-        bluedroid/api
-        )
-
-endif()
+# currently uses libcoap's hash table in hashkey.h
+set(COMPONENT_REQUIRES coap)
 
 register_component()
 
-target_link_libraries(bt "-L${CMAKE_CURRENT_LIST_DIR}/lib")
-target_link_libraries(bt btdm_app)
+if(CONFIG_BT_ENABLED)
+    target_link_libraries(bt "-L${CMAKE_CURRENT_LIST_DIR}/lib")
+    target_link_libraries(bt btdm_app)
+endif()
diff --git a/components/coap/CMakeLists.txt b/components/coap/CMakeLists.txt
index cadd463fa..faba93309 100644
--- a/components/coap/CMakeLists.txt
+++ b/components/coap/CMakeLists.txt
@@ -19,6 +19,8 @@ set(COMPONENT_SRCS
     port/coap_io_socket.c
     )
 
+set(COMPONENT_REQUIRES lwip)
+
 register_component()
 
 # Needed for coap headers in public builds, also.
diff --git a/components/console/CMakeLists.txt b/components/console/CMakeLists.txt
index 1c5648654..0b0da5394 100644
--- a/components/console/CMakeLists.txt
+++ b/components/console/CMakeLists.txt
@@ -1,5 +1,7 @@
 set(COMPONENT_ADD_INCLUDEDIRS .)
 set(COMPONENT_SRCDIRS linenoise argtable3 .)
 
+set(COMPONENT_REQUIRES)
+
 register_component()
 
diff --git a/components/cxx/CMakeLists.txt b/components/cxx/CMakeLists.txt
index 255f4f3fd..a797640cc 100644
--- a/components/cxx/CMakeLists.txt
+++ b/components/cxx/CMakeLists.txt
@@ -1,4 +1,5 @@
 set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_REQUIRES)
 register_component()
 
 target_link_libraries(cxx stdc++)
diff --git a/components/driver/CMakeLists.txt b/components/driver/CMakeLists.txt
index 8ccaad2c3..0c72aecc4 100644
--- a/components/driver/CMakeLists.txt
+++ b/components/driver/CMakeLists.txt
@@ -2,4 +2,6 @@ set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS "include/driver")
 
+set(COMPONENT_REQUIRES)
+
 register_component()
diff --git a/components/esp-tls/CMakeLists.txt b/components/esp-tls/CMakeLists.txt
new file mode 100644
index 000000000..9bad42868
--- /dev/null
+++ b/components/esp-tls/CMakeLists.txt
@@ -0,0 +1,7 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS ".")
+
+set(COMPONENT_REQUIRES mbedtls)
+set(COMPONENT_PRIV_REQUIRES lwip nghttp)
+
+register_component()
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 1172dda7f..b231bfd0d 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -1,7 +1,9 @@
 if(BOOTLOADER_BUILD)
     # For bootloader, all we need from esp32 is headers
-    add_library(esp32 INTERFACE)
-    target_include_directories(esp32 INTERFACE include)
+    set(COMPONENT_ADD_INCLUDEDIRS include)
+    set(COMPONENT_REQUIRES ${COMPONENTS})
+    set(COMPONENT_SRCDIRS "")
+    register_component(esp32)
 
     # as cmake won't attach linker args to a header-only library, attach
     # linker args directly to the bootloader.elf
@@ -18,6 +20,11 @@ else()
     set(COMPONENT_SRCDIRS ". hwcrypto")
     set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+    set(COMPONENT_REQUIRES driver)  # required because esp_sleep.h uses gpio_num_t & touch_pad_t
+    set(COMPONENT_PRIV_REQUIRES
+        adapter app bootloader_debug ethernet_flash flash_log mbedtls_module nvs_pthread
+        spi-supplicant-support tcpip trace_vfs wpa xtensa)
+
     register_component()
 
     target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
diff --git a/components/esp_adc_cal/CMakeLists.txt b/components/esp_adc_cal/CMakeLists.txt
index ba2fa9c7e..fc21f1eca 100644
--- a/components/esp_adc_cal/CMakeLists.txt
+++ b/components/esp_adc_cal/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES)
+
 register_component()
diff --git a/components/ethernet/CMakeLists.txt b/components/ethernet/CMakeLists.txt
index a9eb90370..165d89fbe 100644
--- a/components/ethernet/CMakeLists.txt
+++ b/components/ethernet/CMakeLists.txt
@@ -1,4 +1,7 @@
 set(COMPONENT_SRCDIRS . eth_phy)
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES)
+set(COMPONENT_PRIV_REQUIRES tcpip_adapter)
+
 register_component()
diff --git a/components/expat/CMakeLists.txt b/components/expat/CMakeLists.txt
index 9e77a825c..5791a2659 100644
--- a/components/expat/CMakeLists.txt
+++ b/components/expat/CMakeLists.txt
@@ -1,6 +1,8 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include include/expat)
 set(COMPONENT_SRCDIRS library port)
 
+set(COMPONENT_REQUIRES)
+
 register_component()
 
 component_compile_definitions(HAVE_EXPAT_CONFIG_H)
diff --git a/components/fatfs/CMakeLists.txt b/components/fatfs/CMakeLists.txt
index c9f5a0fcf..3d24c50bf 100644
--- a/components/fatfs/CMakeLists.txt
+++ b/components/fatfs/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS src)
 set(COMPONENT_ADD_INCLUDEDIRS src)
 
+set(COMPONENT_REQUIRES wear_levelling sdmmc)
+
 register_component()
diff --git a/components/freertos/CMakeLists.txt b/components/freertos/CMakeLists.txt
index 0a5172dc1..a0be8f086 100644
--- a/components/freertos/CMakeLists.txt
+++ b/components/freertos/CMakeLists.txt
@@ -1,6 +1,8 @@
 set(COMPONENT_ADD_INCLUDEDIRS include)
 set(COMPONENT_PRIV_INCLUDEDIRS include/freertos)
 set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_REQUIRES)
+
 register_component()
 
 target_link_libraries(freertos "-Wl,--undefined=uxTopUsedPriority")
diff --git a/components/heap/CMakeLists.txt b/components/heap/CMakeLists.txt
index 08e78e845..b7dd5d9ac 100644
--- a/components/heap/CMakeLists.txt
+++ b/components/heap/CMakeLists.txt
@@ -6,6 +6,8 @@ endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES "")
+
 register_component()
 
 if(CONFIG_HEAP_TRACING)
diff --git a/components/idf_test/CMakeLists.txt b/components/idf_test/CMakeLists.txt
index e307838a8..cf64054dd 100644
--- a/components/idf_test/CMakeLists.txt
+++ b/components/idf_test/CMakeLists.txt
@@ -1,2 +1,3 @@
 set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES)
 register_component()
diff --git a/components/jsmn/CMakeLists.txt b/components/jsmn/CMakeLists.txt
index 2eabcf5fe..7c19d9ccb 100644
--- a/components/jsmn/CMakeLists.txt
+++ b/components/jsmn/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS "src")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES "")
+
 register_component()
diff --git a/components/json/CMakeLists.txt b/components/json/CMakeLists.txt
index c19ec43fa..0b8ba83d6 100644
--- a/components/json/CMakeLists.txt
+++ b/components/json/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS cJSON)
 set(COMPONENT_ADD_INCLUDEDIRS cJSON)
 
+set(COMPONENT_REQUIRES "")
+
 register_component()
diff --git a/components/libsodium/CMakeLists.txt b/components/libsodium/CMakeLists.txt
index 48e5a3f69..674534c91 100644
--- a/components/libsodium/CMakeLists.txt
+++ b/components/libsodium/CMakeLists.txt
@@ -1,5 +1,7 @@
 set(SRC libsodium/src/libsodium)
 
+set(COMPONENT_REQUIRES "mbedtls")
+
 set(COMPONENT_SRCDIRS
     port
 
diff --git a/components/log/CMakeLists.txt b/components/log/CMakeLists.txt
index eebd20a04..ad162fe1e 100644
--- a/components/log/CMakeLists.txt
+++ b/components/log/CMakeLists.txt
@@ -1,3 +1,4 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES)
 register_component()
diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
index 5474c4daa..03deae436 100644
--- a/components/lwip/CMakeLists.txt
+++ b/components/lwip/CMakeLists.txt
@@ -16,6 +16,9 @@ set(COMPONENT_SRCDIRS
     ${LWIP_PPP_DIRS} netif
     port/freertos port/netif port/debug port)
 
+set(COMPONENT_REQUIRES "")
+set(COMPONENT_PRIV_REQUIRES ethernet tcpip_adapter)
+
 register_component()
 
 component_compile_options(-Wno-address)
diff --git a/components/mbedtls/CMakeLists.txt b/components/mbedtls/CMakeLists.txt
index 56dfce17c..44410c149 100644
--- a/components/mbedtls/CMakeLists.txt
+++ b/components/mbedtls/CMakeLists.txt
@@ -1,6 +1,8 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include include)
 set(COMPONENT_SRCDIRS library port)
 
+set(COMPONENT_REQUIRES lwip)
+
 register_component()
 
 target_compile_definitions(mbedtls PUBLIC
diff --git a/components/mdns/CMakeLists.txt b/components/mdns/CMakeLists.txt
index 149dcb0bc..4ab664110 100644
--- a/components/mdns/CMakeLists.txt
+++ b/components/mdns/CMakeLists.txt
@@ -1,5 +1,7 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS "private_include")
+set(COMPONENT_REQUIRES lwip mbedtls console tcpip_adapter)
+
 register_component()
 
diff --git a/components/micro-ecc/CMakeLists.txt b/components/micro-ecc/CMakeLists.txt
index 13bc9cfb6..24e0a9e6f 100644
--- a/components/micro-ecc/CMakeLists.txt
+++ b/components/micro-ecc/CMakeLists.txt
@@ -3,4 +3,6 @@ set(COMPONENT_SRCS micro-ecc/uECC.c)
 
 set(COMPONENT_ADD_INCLUDEDIRS micro-ecc)
 
+set(COMPONENT_REQUIRES)
+
 register_component()
diff --git a/components/newlib/CMakeLists.txt b/components/newlib/CMakeLists.txt
index c92518deb..4bc0db3f9 100644
--- a/components/newlib/CMakeLists.txt
+++ b/components/newlib/CMakeLists.txt
@@ -15,6 +15,8 @@ else()
     set(LIBM m)
 endif()
 
+set(COMPONENT_REQUIRES vfs)  # for sys/ioctl.h
+
 register_component()
 
 target_link_libraries(newlib "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
diff --git a/components/nghttp/CMakeLists.txt b/components/nghttp/CMakeLists.txt
index c7e4b754b..bf3f72746 100644
--- a/components/nghttp/CMakeLists.txt
+++ b/components/nghttp/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include nghttp2/lib/includes)
 set(COMPONENT_SRCDIRS nghttp2/lib port)
 
+set(COMPONENT_REQUIRES lwip mbedtls)
+
 register_component()
diff --git a/components/nvs_flash/CMakeLists.txt b/components/nvs_flash/CMakeLists.txt
index 5970a7915..1fe5ecf26 100644
--- a/components/nvs_flash/CMakeLists.txt
+++ b/components/nvs_flash/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS src)
 set(COMPONENT_ADD_INCLUDEDIRS include)
 
+set(COMPONENT_REQUIRES spi_flash)
+
 register_component()
diff --git a/components/openssl/CMakeLists.txt b/components/openssl/CMakeLists.txt
index 347ade638..84d02ffe8 100644
--- a/components/openssl/CMakeLists.txt
+++ b/components/openssl/CMakeLists.txt
@@ -2,4 +2,6 @@ set(COMPONENT_ADD_INCLUDEDIRS include)
 set(COMPONENT_PRIV_INCLUDEDIRS include/internal include/platform include/openssl)
 set(COMPONENT_SRCDIRS library platform)
 
+set(COMPONENT_REQUIRES mbedtls)
+
 register_component()
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index 87f12da94..cde193dce 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -1,5 +1,7 @@
 set(partition_table_offset 0x8000)
 
+register_config_only_component()
+
 # Set partition_csv to the configured partition source file
 #
 if(CONFIG_PARTITION_TABLE_CUSTOM)
@@ -56,4 +58,3 @@ set_property(GLOBAL APPEND_STRING PROPERTY
     ESPTOOL_WRITE_FLASH_ARGS
     "${partition_table_offset} ${final_partition_bin} ")
 
-register_config_only_component()
diff --git a/components/pthread/CMakeLists.txt b/components/pthread/CMakeLists.txt
index eebd20a04..ad162fe1e 100644
--- a/components/pthread/CMakeLists.txt
+++ b/components/pthread/CMakeLists.txt
@@ -1,3 +1,4 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES)
 register_component()
diff --git a/components/sdmmc/CMakeLists.txt b/components/sdmmc/CMakeLists.txt
index ba2fa9c7e..58b9aeb67 100644
--- a/components/sdmmc/CMakeLists.txt
+++ b/components/sdmmc/CMakeLists.txt
@@ -1,4 +1,4 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
-
+set(COMPONENT_REQUIRES driver)
 register_component()
diff --git a/components/smartconfig/CMakeLists.txt b/components/smartconfig/CMakeLists.txt
index ba2fa9c7e..8b18007de 100644
--- a/components/smartconfig/CMakeLists.txt
+++ b/components/smartconfig/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_PRIV_REQUIRES lwip tcpip_adapter)
+
 register_component()
diff --git a/components/soc/CMakeLists.txt b/components/soc/CMakeLists.txt
index 24e859551..b4c088edd 100644
--- a/components/soc/CMakeLists.txt
+++ b/components/soc/CMakeLists.txt
@@ -3,4 +3,7 @@ set(SOC_NAME esp32)
 set(COMPONENT_SRCDIRS ${SOC_NAME})
 set(COMPONENT_ADD_INCLUDEDIRS ${SOC_NAME}/include include)
 
+set(COMPONENT_REQUIRES)
+
+
 register_component()
diff --git a/components/spi_flash/CMakeLists.txt b/components/spi_flash/CMakeLists.txt
index f64a6ec11..1eafba54d 100644
--- a/components/spi_flash/CMakeLists.txt
+++ b/components/spi_flash/CMakeLists.txt
@@ -2,10 +2,13 @@ if(BOOTLOADER_BUILD)
     # Bootloader needs SPIUnlock from this file, but doesn't
     # need other parts of this component
     set(COMPONENT_SRCS spi_flash_rom_patch.c)
+    set(COMPONENT_PRIV_REQUIRES bootloader_support)
 else()
     set(COMPONENT_SRCDIRS .)
+    set(COMPONENT_PRIV_REQUIRES bootloader_support app_update)
 endif()
 
 set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_REQUIRES)
 
 register_component()
diff --git a/components/spiffs/CMakeLists.txt b/components/spiffs/CMakeLists.txt
index 5e0027f52..a85f98d2b 100644
--- a/components/spiffs/CMakeLists.txt
+++ b/components/spiffs/CMakeLists.txt
@@ -1,5 +1,9 @@
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS "spiffs/src")
 set(COMPONENT_SRCDIRS ". spiffs/src")
+
+set(COMPONENT_REQUIRES spi_flash)
+set(COMPONENT_PRIV_REQUIRES bootloader_support)
+
 register_component()
 
diff --git a/components/tcpip_adapter/CMakeLists.txt b/components/tcpip_adapter/CMakeLists.txt
index ba2fa9c7e..24deb2f24 100644
--- a/components/tcpip_adapter/CMakeLists.txt
+++ b/components/tcpip_adapter/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES lwip)
+
 register_component()
diff --git a/components/ulp/CMakeLists.txt b/components/ulp/CMakeLists.txt
index ba2fa9c7e..fc21f1eca 100644
--- a/components/ulp/CMakeLists.txt
+++ b/components/ulp/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES)
+
 register_component()
diff --git a/components/vfs/CMakeLists.txt b/components/vfs/CMakeLists.txt
index ba2fa9c7e..fc21f1eca 100644
--- a/components/vfs/CMakeLists.txt
+++ b/components/vfs/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES)
+
 register_component()
diff --git a/components/wear_levelling/CMakeLists.txt b/components/wear_levelling/CMakeLists.txt
index a72d0f565..8b5db6231 100644
--- a/components/wear_levelling/CMakeLists.txt
+++ b/components/wear_levelling/CMakeLists.txt
@@ -1,4 +1,5 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_PRIV_INCLUDEDIRS private_include)
+set(COMPONENT_REQUIRES spi_flash)
 register_component()
diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
index 1d2091656..fc0c323fc 100644
--- a/components/wpa_supplicant/CMakeLists.txt
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -1,6 +1,9 @@
 set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto)
 set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 
+set(COMPONENT_REQUIRES "")
+set(COMPONENT_PRIV_REQUIRES lwip mbedtls)
+
 register_component()
 
 component_compile_definitions(__ets__)
diff --git a/components/xtensa-debug-module/CMakeLists.txt b/components/xtensa-debug-module/CMakeLists.txt
index ba2fa9c7e..810d299d1 100644
--- a/components/xtensa-debug-module/CMakeLists.txt
+++ b/components/xtensa-debug-module/CMakeLists.txt
@@ -1,4 +1,6 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
+set(COMPONENT_REQUIRES "")
+
 register_component()
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index a4de84060..03eb0c206 100644
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -78,7 +78,7 @@ The :ref:`getting started guide <get-started-configure-cmake>` contains a brief
 
 ``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
 
-Type ``idf.py --help`` for a full list of commands. Here are a summary of a few:
+Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
 
 - ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
 - ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
@@ -207,7 +207,8 @@ These variables all have default values that can be overridden for custom behavi
 
 - ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
 - ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
-- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times.
+- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list doesn't need to include dependencies in this way.
+- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically treated to be in every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this is set to the minimal set of core "system" components needed for any ESP-IDF project.
 
 Any paths in these variables can be absolute paths, or set relative to the project directory.
 
@@ -273,22 +274,18 @@ The following variables are set at the project level, but available for use in c
 
 If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
 
-Optional Project-Wide Component Variables
------------------------------------------
-
-The following variables can be set inside component ``CMakeLists.txt`` to control build settings across the entire project:
 
 - ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
   directory, which will be added to the include search path for
-  all components in the project. If an include directory is only needed to compile
+  all other components which require this one. If an include directory is only needed to compile
   this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
-- ``COMPONENT_DEPENDS``: Optional list of component names that should be
-  compiled before this component. This is not necessary for
-  link-time dependencies, because all component include directories
-  are available at all times. It is necessary if one component
-  generates an include file which you then want to include in another
-  component. Most components do not need to set this variable.
+- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If a public header header file listed in ``COMPONENT_ADD_INCLUDEDIRS`` includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
 
+  The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
+
+  If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
+
+  See `Component Requirements` for more details.
 
 Optional Component-Specific Variables
 -------------------------------------
@@ -298,6 +295,7 @@ The following variables can be set inside ``component.mk`` to control the build
 - ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
   the component directory, which will be added to the include search
   path for this component's source files only.
+- ``COMPONENT_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details.
 - ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
   component directory, which will be searched for source files (``*.cpp``,
   ``*.c``, ``*.S``). Set this to specify a list of directories
@@ -345,6 +343,45 @@ The ESP-IDF build system adds the following C preprocessor definitions on the co
 - ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
 - ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
 
+Component Requirements
+======================
+
+When compiling each component, the ESP-IDF build system recurisvely evaluates its components.
+
+Each component's source file is compiled with these include path directories:
+
+- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
+- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
+- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
+
+When writing a component
+------------------------
+
+- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
+- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
+- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
+- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
+- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
+
+When creating a project
+-----------------------
+
+- By default, every component is included in the build.
+- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
+  - Components mentioned explicitly in ``COMPONENTS``.
+  - Those components' requirements (evaluated recursively).
+  - The "common" components that every component depends on.
+- Setting ``COMPONENTS`` to the minimal list of components you need can significantly reduce your project's compile time.
+- When compiling the project's source files (``MAIN_SRCS``), the public header directories of all components included in the build are available.
+
+Requirements in the build system implementation
+------------------------------------------------------------------
+
+- Very early in the cmake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
+- The main cmake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
+- Configuration is then evaluated for the components included in the build.
+- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
+
 Build Process Internals
 =======================
 
@@ -362,6 +399,7 @@ project function
 
 The custom ``project()`` function performs the following steps:
 
+- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see `above<requirements-in-the-build-system-implementation>`).
 - Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
 - Loads the project configuration from the ``sdkconfig`` file and produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
 - Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
@@ -525,10 +563,8 @@ why it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
 
 (Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
 
-If a a source file from another component included ``logo.h``, then this
-component's name would have to be added to the other component's
-``COMPONENT_DEPENDS`` list to ensure that the components were built
-in-order.
+If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
+the two components, to ensure that the component source files were always compiled in the correct order.
 
 Embedding Binary Data
 ---------------------
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index e638a36d0..8d3830c8b 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -202,7 +202,7 @@ The following variables can be set inside ``component.mk`` to control build sett
   the app executable. Defaults to ``-l$(COMPONENT_NAME)``.  If
   adding pre-compiled libraries to this directory, add them as
   absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
-- ``COMPONENT_DEPENDS``: Optional list of component names that should
+- ``COMPONENT_REQUIRES``: Optional list of component names that should
   be compiled before this component. This is not necessary for
   link-time dependencies, because all component include directories
   are available at all times. It is necessary if one component
@@ -544,7 +544,7 @@ generated before ``graphics_lib.c`` is compiled.
 
 If a a source file in another component included ``logo.h``, then this
 component's name would have to be added to the other component's
-``COMPONENT_DEPENDS`` list to ensure that the components were built
+``COMPONENT_REQUIRES`` list to ensure that the components were built
 in-order.
 
 Embedding Binary Data
diff --git a/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt b/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
index 74bb26787..6d19bf48b 100644
--- a/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
+++ b/examples/protocols/http2_request/components/sh2lib/CMakeLists.txt
@@ -2,4 +2,7 @@ set(COMPONENT_ADD_INCLUDEDIRS .)
 
 set(COMPONENT_SRCDIRS .)
 
+set(COMPONENT_REQUIRES nghttp)
+set(COMPONENT_PRIV_REQUIRES lwip esp-tls)
+
 register_component()
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 4334ffee7..506d8a06f 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -1,53 +1,16 @@
-# Search 'component_dirs' for components and return them
-# as a list of names in 'component_names' and a list of full paths in
-# 'component_paths'
-#
-# component_paths contains only unique component names. Directories
-# earlier in the component_dirs list take precedence.
-function(components_find_all component_dirs filter_names component_paths component_names)
-    # component_dirs entries can be files or lists of files
-    set(paths "")
-    set(names "")
-
-    # start by expanding the component_dirs list with all subdirectories
-    foreach(dir ${component_dirs})
-        # Iterate any subdirectories for values
-        file(GLOB subdirs LIST_DIRECTORIES true "${dir}/*")
-        foreach(subdir ${subdirs})
-            set(component_dirs "${component_dirs};${subdir}")
-        endforeach()
-    endforeach()
-
-    # Look for a component in each component_dirs entry
-    foreach(dir ${component_dirs})
-        file(GLOB component "${dir}/CMakeLists.txt")
-        if(component)
-            get_filename_component(component "${component}" DIRECTORY)
-            get_filename_component(name "${component}" NAME)
-            if(NOT filter_names OR (name IN_LIST filter_names))
-                if(NOT name IN_LIST names)
-                    set(names "${names};${name}")
-                    set(paths "${paths};${component}")
-                endif()
-            endif()
-
-        else()  # no CMakeLists.txt file
-            # test for legacy component.mk and warn
-            file(GLOB legacy_component "${dir}/component.mk")
-            if(legacy_component)
-                get_filename_component(legacy_component "${legacy_component}" DIRECTORY)
-                message(WARNING "Component ${legacy_component} contains old-style component.mk but no CMakeLists.txt. "
-                    "Component will be skipped.")
-            endif()
+# Given a list of components in 'component_paths', filter only paths to the components
+# mentioned in 'components' and return as a list in 'result_paths'
+function(components_get_paths component_paths components result_paths)
+    set(result "")
+    foreach(path ${component_paths})
+        get_filename_component(name "${path}" NAME)
+        if("${name}" IN_LIST components)
+            list(APPEND result "${name}")
         endif()
-
     endforeach()
-
-    set(${component_paths} ${paths} PARENT_SCOPE)
-    set(${component_names} ${names} PARENT_SCOPE)
+    set("${result_path}" "${result}" PARENT_SCOPE)
 endfunction()
 
-
 # Add a component to the build, using the COMPONENT variables defined
 # in the parent
 #
@@ -76,7 +39,7 @@ function(register_component)
         endforeach()
     endif()
 
-    # add public includes from other components when building this component
+    # add as a PUBLIC library (if there are source files) or INTERFACE (if header only)
     if(COMPONENT_SRCS OR embed_binaries)
         add_library(${component} STATIC ${COMPONENT_SRCS})
         set(include_type PUBLIC)
@@ -97,7 +60,7 @@ function(register_component)
         target_add_binary_data("${component}" "${embed_data}" "${embed_type}")
     endforeach()
 
-    # add public includes
+    # add component public includes
     foreach(include_dir ${COMPONENT_ADD_INCLUDEDIRS})
         get_filename_component(abs_dir ${include_dir} ABSOLUTE BASE_DIR ${component_dir})
         if(NOT IS_DIRECTORY ${abs_dir})
@@ -107,7 +70,7 @@ function(register_component)
         target_include_directories(${component} ${include_type} ${abs_dir})
     endforeach()
 
-    # add private includes
+    # add component private includes
     foreach(include_dir ${COMPONENT_PRIV_INCLUDEDIRS})
         if(${include_type} STREQUAL INTERFACE)
             message(FATAL_ERROR "${CMAKE_CURRENT_LIST_FILE} "
@@ -121,7 +84,6 @@ function(register_component)
         endif()
         target_include_directories(${component} PRIVATE ${abs_dir})
     endforeach()
-
 endfunction()
 
 function(register_config_only_component)
@@ -131,30 +93,47 @@ function(register_config_only_component)
     # No-op for now...
 endfunction()
 
-function(components_finish_registration)
-    # each component should see the include directories of each other
-    #
-    # (we can't do this until all components are registered, because if(TARGET ...) won't work
-    foreach(a ${COMPONENTS} ${CMAKE_PROJECT_NAME}.elf)
-        if(TARGET ${a})
-            get_target_property(a_imported ${a} IMPORTED)
-            get_target_property(a_type ${a} TYPE)
-            if(NOT a_imported)
-                if(${a_type} STREQUAL STATIC_LIBRARY OR ${a_type} STREQUAL EXECUTABLE)
-                    foreach(b ${COMPONENTS})
-                        if(TARGET ${b} AND NOT ${a} STREQUAL ${b})
-                            # Add all public compile options from b in a
-                            target_include_directories(${a} PRIVATE
-                                $<TARGET_PROPERTY:${b},INTERFACE_INCLUDE_DIRECTORIES>)
-                            target_compile_definitions(${a} PRIVATE
-                                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_DEFINITIONS>)
-                            target_compile_options(${a} PRIVATE
-                                $<TARGET_PROPERTY:${b},INTERFACE_COMPILE_OPTIONS>)
-                        endif()
-                    endforeach(b)
-                endif()
-            endif()
+function(add_component_dependencies target dep dep_type)
+    get_target_property(target_type ${target} TYPE)
+    get_target_property(target_imported ${target} IMPORTED)
 
+    if(${target_type} STREQUAL STATIC_LIBRARY OR ${target_type} STREQUAL EXECUTABLE)
+        if(TARGET ${dep})
+            # Add all compile options exported by dep into target
+            target_include_directories(${target} ${dep_type}
+                $<TARGET_PROPERTY:${dep},INTERFACE_INCLUDE_DIRECTORIES>)
+            target_compile_definitions(${target} ${dep_type}
+                $<TARGET_PROPERTY:${dep},INTERFACE_COMPILE_DEFINITIONS>)
+            target_compile_options(${target} ${dep_type}
+                $<TARGET_PROPERTY:${dep},INTERFACE_COMPILE_OPTIONS>)
+        endif()
+    endif()
+endfunction()
+
+function(components_finish_registration)
+
+    # have the executable target depend on all components in the build
+    set_target_properties(${CMAKE_PROJECT_NAME}.elf PROPERTIES INTERFACE_COMPONENT_REQUIRES "${BUILD_COMPONENTS}")
+
+    spaces2list(COMPONENT_REQUIRES_COMMON)
+
+    # each component should see the include directories of its requirements
+    #
+    # (we can't do this until all components are registered and targets exist in cmake, as we have
+    # a circular requirements graph...)
+    foreach(a ${BUILD_COMPONENTS})
+        if(TARGET ${a})
+            get_component_requirements("${a}" a_deps a_priv_deps)
+            list(APPEND a_priv_deps ${COMPONENT_REQUIRES_COMMON})
+            foreach(b ${a_deps})
+                add_component_dependencies(${a} ${b} PUBLIC)
+            endforeach()
+
+            foreach(b ${a_priv_deps})
+                add_component_dependencies(${a} ${b} PRIVATE)
+            endforeach()
+
+            get_target_property(a_type ${a} TYPE)
             if(${a_type} MATCHES .+_LIBRARY)
                 set(COMPONENT_LIBRARIES "${COMPONENT_LIBRARIES};${a}")
             endif()
@@ -164,7 +143,7 @@ function(components_finish_registration)
     # Add each component library's link-time dependencies (which are otherwise ignored) to the executable
     # LINK_DEPENDS in order to trigger a re-link when needed (on Ninja/Makefile generators at least).
     # (maybe this should probably be something CMake does, but it doesn't do it...)
-    foreach(component ${COMPONENTS})
+    foreach(component ${BUILD_COMPONENTS})
         if(TARGET ${component})
             get_target_property(imported ${component} IMPORTED)
             get_target_property(type ${component} TYPE)
@@ -179,16 +158,6 @@ function(components_finish_registration)
         endif()
     endforeach()
 
-    # Embedded binary & text files
-    spaces2list(COMPONENT_EMBED_FILES)
-    foreach(embed_src ${COMPONENT_EMBED_FILES})
-        target_add_binary_data(${component} "${embed_src}" BINARY)
-    endforeach()
-    spaces2list(COMPONENT_EMBED_TXTFILES)
-    foreach(embed_src ${COMPONENT_EMBED_TXTFILES})
-        target_add_binary_data(${component} "${embed_src}" TEXT)
-    endforeach()
-
     target_link_libraries(${CMAKE_PROJECT_NAME}.elf ${COMPONENT_LIBRARIES})
 
     message(STATUS "Component libraries: ${COMPONENT_LIBRARIES}")
diff --git a/tools/cmake/convert_to_cmake.py b/tools/cmake/convert_to_cmake.py
index 0cfd60263..82e697171 100755
--- a/tools/cmake/convert_to_cmake.py
+++ b/tools/cmake/convert_to_cmake.py
@@ -180,6 +180,11 @@ def convert_component(project_path, component_path):
 
     with open(cmakelists_path, "w") as f:
         f.write("set(COMPONENT_ADD_INCLUDEDIRS %s)\n\n" % component_add_includedirs)
+
+        f.write("# Edit following two lines to set component requirements (see docs)\n")
+        f.write("set(COMPONENT_REQUIRES "")\n")
+        f.write("set(COMPONENT_PRIV_REQUIRES "")\n\n")
+
         if component_srcdirs is not None:
             f.write("set(COMPONENT_SRCDIRS %s)\n\n" % component_srcdirs)
             f.write("register_component()\n")
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index e88e980af..3415f9da2 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -13,6 +13,10 @@ macro(idf_set_global_variables)
 
     set_default(EXTRA_COMPONENT_DIRS "")
 
+    # Commmon components, required by every component in the build
+    #
+    set_default(COMPONENT_REQUIRES_COMMON "cxx esp32 newlib freertos heap log soc")
+
     # PROJECT_PATH has the path to the IDF project (top-level cmake directory)
     #
     # (cmake calls this CMAKE_SOURCE_DIR, keeping old name for compatibility.)
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index cc2156305..e313c886a 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -35,7 +35,7 @@ function(kconfig_process_config)
 
     # Find Kconfig and Kconfig.projbuild for each component as applicable
     # if any of these change, cmake should rerun
-    foreach(dir ${COMPONENT_PATHS} "${CMAKE_SOURCE_DIR}/main")
+    foreach(dir ${BUILD_COMPONENT_PATHS} "${CMAKE_SOURCE_DIR}/main")
         file(GLOB kconfig "${dir}/Kconfig")
         if(kconfig)
             set(kconfigs "${kconfigs} ${kconfig}")
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 26be56eda..ff344a967 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -46,16 +46,32 @@ macro(project name)
     # Set global variables used by rest of the build
     idf_set_global_variables()
 
-    # Search COMPONENT_DIRS for COMPONENTS, make a list of full paths to each
-    # component in COMPONENT_PATHS
-    components_find_all("${COMPONENT_DIRS}" "${COMPONENTS}"
-        COMPONENT_PATHS COMPONENTS)
+    # Establish dependencies for components in the build
+    # (this happens before we even generate config...)
+    if(COMPONENTS)
+        # Make sure if an explicit list of COMPONENTS is given, it contains the "common" component requirements
+        # (otherwise, if COMPONENTS is empty then all components will be included in the build.)
+        set(COMPONENTS "${COMPONENTS} ${COMPONENT_REQUIRES_COMMON}")
+    endif()
+    execute_process(COMMAND "${CMAKE_COMMAND}"
+        -D "COMPONENTS=${COMPONENTS}"
+        -D "DEPENDENCIES_FILE=${CMAKE_BINARY_DIR}/component_depends.cmake"
+        -D "COMPONENT_DIRS=${COMPONENT_DIRS}"
+        -D "BOOTLOADER_BUILD=${BOOTLOADER_BUILD}"
+        -P "${IDF_PATH}/tools/cmake/scripts/expand_requirements.cmake"
+        WORKING_DIRECTORY "${IDF_PATH}/tools/cmake")
+    include("${CMAKE_BINARY_DIR}/component_depends.cmake")
+
+    # We now have the following component-related variables:
+    # COMPONENTS is the list of initial components set by the user (or empty to include all components in the build).
+    # BUILD_COMPONENTS is the list of components to include in the build.
+    # BUILD_COMPONENT_PATHS is the paths to all of these components.
 
     # Print list of components
-    string(REPLACE ";" " " COMPONENTS_SPACES "${COMPONENTS}")
-    message(STATUS "Component names: ${COMPONENTS_SPACES}")
-    unset(COMPONENTS_SPACES)
-    message(STATUS "Component paths: ${COMPONENT_PATHS}")
+    string(REPLACE ";" " " BUILD_COMPONENTS_SPACES "${BUILD_COMPONENTS}")
+    message(STATUS "Component names: ${BUILD_COMPONENTS_SPACES}")
+    unset(BUILD_COMPONENTS_SPACES)
+    message(STATUS "Component paths: ${BUILD_COMPONENT_PATHS}")
 
     kconfig_set_variables()
 
@@ -88,14 +104,14 @@ macro(project name)
     git_describe(PROJECT_VER "${CMAKE_CURRENT_SOURCE_DIR}")
 
     # Include any top-level project_include.cmake files from components
-    foreach(component ${COMPONENT_PATHS})
+    foreach(component ${BUILD_COMPONENT_PATHS})
         include_if_exists("${component}/project_include.cmake")
     endforeach()
 
     #
     # Add each component to the build as a library
     #
-    foreach(COMPONENT_PATH ${COMPONENT_PATHS})
+    foreach(COMPONENT_PATH ${BUILD_COMPONENT_PATHS})
         get_filename_component(COMPONENT_NAME ${COMPONENT_PATH} NAME)
         add_subdirectory(${COMPONENT_PATH} ${COMPONENT_NAME})
     endforeach()
diff --git a/tools/cmake/scripts/expand_requirements.cmake b/tools/cmake/scripts/expand_requirements.cmake
new file mode 100644
index 000000000..9b56cf090
--- /dev/null
+++ b/tools/cmake/scripts/expand_requirements.cmake
@@ -0,0 +1,216 @@
+# expand_requires.cmake is a utility cmake script to expand component requirements early in the build,
+# before the components are ready to be included.
+#
+# Parameters:
+# - COMPONENTS = Space-separated list of initial components to include in the build.
+#   Can be empty, in which case all components are in the build.
+# - DEPENDENCIES_FILE = Path of generated cmake file which will contain the expanded dependencies for these
+#   components.
+# - COMPONENT_DIRS = List of paths to search for all components.
+# - DEBUG = Set -DDEBUG=1 to debug component lists in the build.
+#
+# If successful, DEPENDENCIES_FILE can be expanded to set BUILD_COMPONENTS & BUILD_COMPONENT_PATHS with all
+# components required for the build, and the get_component_requirements() function to return each component's
+# recursively expanded requirements.
+#
+# TODO: Error out if a component requirement is missing
+cmake_minimum_required(VERSION 3.5)
+include("utilities.cmake")
+
+if(NOT DEPENDENCIES_FILE)
+    message(FATAL_ERROR "DEPENDENCIES_FILE must be set.")
+endif()
+
+if(NOT COMPONENT_DIRS)
+    message(FATAL_ERROR "COMPONENT_DIRS variable must be set")
+endif()
+spaces2list(COMPONENT_DIRS)
+
+function(debug message)
+    if(DEBUG)
+        message(STATUS "${message}")
+    endif()
+endfunction()
+
+# Dummy register_component used to save requirements variables as global properties, for later expansion
+#
+# (expand_component_requirements() includes the component CMakeLists.txt, which then sets its component variables,
+# calls this dummy macro, and immediately exits again.)
+macro(register_component)
+    spaces2list(COMPONENT_REQUIRES)
+    set_property(GLOBAL PROPERTY "${COMPONENT}_REQUIRES" "${COMPONENT_REQUIRES}")
+    spaces2list(COMPONENT_PRIV_REQUIRES)
+    set_property(GLOBAL PROPERTY "${COMPONENT}_PRIV_REQUIRES" "${COMPONENT_PRIV_REQUIRES}")
+
+    # This is tricky: we override register_component() so it returns out of the component CMakeLists.txt
+    # (as we're declaring it as a macro not a function, so it doesn't have its own scope.)
+    #
+    # This means no targets are defined, and the component expansion ends early.
+    return()
+endmacro()
+
+macro(register_config_only_component)
+    register_component()
+endmacro()
+
+# Given a component name (find_name) and a list of component paths (component_paths),
+# return the path to the component in 'variable'
+#
+# Fatal error is printed if the component is not found.
+function(find_component_path find_name component_paths variable)
+    foreach(path ${component_paths})
+        get_filename_component(name "${path}" NAME)
+        if("${name}" STREQUAL "${find_name}")
+            set("${variable}" "${path}" PARENT_SCOPE)
+            return()
+        endif()
+    endforeach()
+    # TODO: find a way to print the dependency chain that lead to this not-found component
+    message(WARNING "Required component ${find_name} is not found in any of the provided COMPONENT_DIRS")
+endfunction()
+
+# components_find_all: Search 'component_dirs' for components and return them
+# as a list of names in 'component_names' and a list of full paths in
+# 'component_paths'
+#
+# component_paths contains only unique component names. Directories
+# earlier in the component_dirs list take precedence.
+function(components_find_all component_dirs component_paths component_names)
+    # component_dirs entries can be files or lists of files
+    set(paths "")
+    set(names "")
+
+    # start by expanding the component_dirs list with all subdirectories
+    foreach(dir ${component_dirs})
+        # Iterate any subdirectories for values
+        file(GLOB subdirs LIST_DIRECTORIES true "${dir}/*")
+        foreach(subdir ${subdirs})
+            set(component_dirs "${component_dirs};${subdir}")
+        endforeach()
+    endforeach()
+
+    # Look for a component in each component_dirs entry
+    foreach(dir ${component_dirs})
+        file(GLOB component "${dir}/CMakeLists.txt")
+        if(component)
+            get_filename_component(component "${component}" DIRECTORY)
+            get_filename_component(name "${component}" NAME)
+            if(NOT name IN_LIST names)
+                set(names "${names};${name}")
+                set(paths "${paths};${component}")
+            endif()
+
+        else()  # no CMakeLists.txt file
+            # test for legacy component.mk and warn
+            file(GLOB legacy_component "${dir}/component.mk")
+            if(legacy_component)
+                get_filename_component(legacy_component "${legacy_component}" DIRECTORY)
+                message(WARNING "Component ${legacy_component} contains old-style component.mk but no CMakeLists.txt. "
+                    "Component will be skipped.")
+            endif()
+        endif()
+
+    endforeach()
+
+    set(${component_paths} ${paths} PARENT_SCOPE)
+    set(${component_names} ${names} PARENT_SCOPE)
+endfunction()
+
+# expand_component_requirements: Recursively expand a component's requirements,
+# setting global properties BUILD_COMPONENTS & BUILD_COMPONENT_PATHS and
+# also invoking the components to call register_component() above,
+# which will add per-component global properties with dependencies, etc.
+function(expand_component_requirements component)
+    get_property(build_components GLOBAL PROPERTY BUILD_COMPONENTS)
+    if(${component} IN_LIST build_components)
+        return()  # already added this component
+    endif()
+
+    find_component_path("${component}" "${ALL_COMPONENT_PATHS}" component_path)
+    debug("Expanding dependencies of ${component} @ ${component_path}")
+    if(NOT component_path)
+        set_property(GLOBAL APPEND PROPERTY COMPONENTS_NOT_FOUND ${component})
+        return()
+    endif()
+
+    # include the component CMakeLists.txt to expand its properties
+    # into the global cache (via register_component(), above)
+    unset(COMPONENT_REQUIRES)
+    unset(COMPONENT_PRIV_REQUIRES)
+    set(COMPONENT ${component})
+    include(${component_path}/CMakeLists.txt)
+
+    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENT_PATHS ${component_path})
+    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENTS ${component})
+
+    get_property(requires GLOBAL PROPERTY "${component}_REQUIRES")
+    get_property(requires_priv GLOBAL PROPERTY "${component}_PRIV_REQUIRES")
+    foreach(req ${requires} ${requires_priv})
+        expand_component_requirements(${req})
+    endforeach()
+endfunction()
+
+
+# Main functionality goes here
+
+# Find every available component in COMPONENT_DIRS, save as ALL_COMPONENT_PATHS and ALL_COMPONENTS
+components_find_all("${COMPONENT_DIRS}" ALL_COMPONENT_PATHS ALL_COMPONENTS)
+
+if(NOT COMPONENTS)
+    set(COMPONENTS "${ALL_COMPONENTS}")
+endif()
+spaces2list(COMPONENTS)
+
+debug("ALL_COMPONENT_PATHS ${ALL_COMPONENT_PATHS}")
+debug("ALL_COMPONENTS ${ALL_COMPONENTS}")
+
+set_property(GLOBAL PROPERTY BUILD_COMPONENTS "")
+set_property(GLOBAL PROPERTY BUILD_COMPONENT_PATHS "")
+set_property(GLOBAL PROPERTY COMPONENTS_NOT_FOUND "")
+
+foreach(component ${COMPONENTS})
+    debug("Expanding initial component ${component}")
+    expand_component_requirements(${component})
+endforeach()
+
+get_property(build_components GLOBAL PROPERTY BUILD_COMPONENTS)
+get_property(build_component_paths GLOBAL PROPERTY BUILD_COMPONENT_PATHS)
+get_property(not_found GLOBAL PROPERTY COMPONENTS_NOT_FOUND)
+
+debug("components in build: ${build_components}")
+debug("components in build: ${build_component_paths}")
+debug("components not found: ${not_found}")
+
+function(line contents)
+    file(APPEND "${DEPENDENCIES_FILE}" "${contents}\n")
+endfunction()
+
+file(WRITE "${DEPENDENCIES_FILE}" "# Component requirements generated by expand_requirements.cmake\n\n")
+line("set(BUILD_COMPONENTS ${build_components})")
+line("set(BUILD_COMPONENT_PATHS ${build_component_paths})")
+line("")
+
+line("# get_component_requirements: Generated function to read the dependencies of a given component.")
+line("#")
+line("# Parameters:")
+line("# - component: Name of component")
+line("# - var_requires: output variable name. Set to recursively expanded COMPONENT_REQUIRES ")
+line("#   for this component.")
+line("# - var_private_requires: output variable name. Set to recursively expanded COMPONENT_PRIV_REQUIRES ")
+line("#   for this component.")
+line("#")
+line("# Throws a fatal error if 'componeont' is not found (indicates a build system problem).")
+line("#")
+line("function(get_component_requirements component var_requires var_private_requires)")
+foreach(build_component ${build_components})
+    get_property(reqs GLOBAL PROPERTY "${build_component}_REQUIRES")
+    get_property(private_reqs GLOBAL PROPERTY "${build_component}_PRIV_REQUIRES")
+    line("  if(\"\$\{component}\" STREQUAL \"${build_component}\")")
+    line("    set(\${var_requires} \"${reqs}\" PARENT_SCOPE)")
+    line("    set(\${var_private_requires} \"${private_reqs}\" PARENT_SCOPE)")
+    line("    return()")
+    line("  endif()")
+endforeach()
+
+line("  message(FATAL_ERROR \"Component not found: \${component}\")")
+line("endfunction()")

From 858b95a92479e8d578d7b755f8fd8e8fd713c754 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 18 Apr 2018 09:30:27 +1000
Subject: [PATCH 045/112] cmake: Add build system tests

---
 .gitlab-ci.yml                                |  13 +
 .../bootloader/subproject/CMakeLists.txt      |   9 +-
 components/esp32/CMakeLists.txt               |  23 +-
 tools/ci/test_build_system_cmake.sh           | 279 ++++++++++++++++++
 tools/cmake/utilities.cmake                   |  31 +-
 5 files changed, 327 insertions(+), 28 deletions(-)
 create mode 100755 tools/ci/test_build_system_cmake.sh

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d18cfa8a3..f0a5fd821 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -313,6 +313,19 @@ test_build_system:
     - cd test_build_system
     - ${IDF_PATH}/tools/ci/test_build_system.sh
 
+test_build_system_cmake:
+  stage: test
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
+  tags:
+    - build_test
+  dependencies: []
+  script:
+    - ${IDF_PATH}/tools/ci/test_configure_ci_environment.sh
+    - rm -rf test_build_system
+    - mkdir test_build_system
+    - cd test_build_system
+    - ${IDF_PATH}/tools/ci/test_build_system_cmake.sh
+
 test_report:
   stage: test_report
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index 719d9fb9d..21a6e84a5 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -16,7 +16,10 @@ set(MAIN_SRCS main/bootloader_start.c)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(bootloader)
 
-target_linker_script(bootloader.elf "main/esp32.bootloader.ld")
-target_linker_script(bootloader.elf "main/esp32.bootloader.rom.ld")
-target_link_libraries(bootloader.elf "${BOOTLOADER_LINKER_ARGS}")
+target_linker_script(bootloader.elf
+    "main/esp32.bootloader.ld"
+    "main/esp32.bootloader.rom.ld")
+# Imported from esp32 component
+target_linker_script(bootloader.elf ${ESP32_BOOTLOADER_LINKER_SCRIPTS})
+
 target_link_libraries(bootloader.elf gcc)
diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index b231bfd0d..2c4fc7429 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -7,12 +7,12 @@ if(BOOTLOADER_BUILD)
 
     # as cmake won't attach linker args to a header-only library, attach
     # linker args directly to the bootloader.elf
-    set(BOOTLOADER_LINKER_ARGS
-        "-L ${CMAKE_CURRENT_SOURCE_DIR}/ld"
-        "-T esp32.rom.ld"
-        "-T esp32.rom.spiram_incompatible_fns.ld"
-        "-T esp32.peripherals.ld"
-        PARENT_SCOPE)
+    set(ESP32_BOOTLOADER_LINKER_SCRIPTS
+        "${CMAKE_CURRENT_SOURCE_DIR}/ld/esp32.rom.ld"
+        "${CMAKE_CURRENT_SOURCE_DIR}/ld/esp32.rom.spiram_incompatible_fns.ld"
+        "${CMAKE_CURRENT_SOURCE_DIR}/ld/esp32.peripherals.ld"
+        PARENT_SCOPE
+        )
 
 else()
     # Regular app build
@@ -22,8 +22,8 @@ else()
 
     set(COMPONENT_REQUIRES driver)  # required because esp_sleep.h uses gpio_num_t & touch_pad_t
     set(COMPONENT_PRIV_REQUIRES
-        adapter app bootloader_debug ethernet_flash flash_log mbedtls_module nvs_pthread
-        spi-supplicant-support tcpip trace_vfs wpa xtensa)
+        app_trace bootloader_support ethernet log mbedtls nvs_flash
+        pthread spi_flash tcpip_adapter vfs wpa_supplicant xtensa-debug-module)
 
     register_component()
 
@@ -33,9 +33,10 @@ else()
     endif()
     target_linker_script(esp32 "${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
 
-    target_linker_script(esp32 "ld/esp32.common.ld")
-    target_linker_script(esp32 "ld/esp32.rom.ld")
-    target_linker_script(esp32 "ld/esp32.peripherals.ld")
+    target_linker_script(esp32
+        "ld/esp32.common.ld"
+        "ld/esp32.rom.ld"
+        "ld/esp32.peripherals.ld")
 
     if(CONFIG_SPIRAM_CACHE_WORKAROUND)
         add_compile_options(-mfix-esp32-psram-cache-issue)
diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh
new file mode 100755
index 000000000..6f245f6b6
--- /dev/null
+++ b/tools/ci/test_build_system_cmake.sh
@@ -0,0 +1,279 @@
+#!/bin/bash
+#
+# Test the build system for basic consistency (Cmake/idf.py version)
+#
+# A bash script that tests some likely build failure scenarios in a row
+#
+# Assumes PWD is an out-of-tree build directory, and will create a
+# subdirectory inside it to run build tests in.
+#
+# Environment variables:
+# IDF_PATH - must be set
+# ESP_IDF_TEMPLATE_GIT - Can override git clone source for template app. Otherwise github.
+# NOCLEANUP - Set to '1' if you want the script to leave its temporary directory when done, for post-mortem.
+#
+#
+# Internals:
+# * The tests run in sequence & the system keeps track of all failures to print at the end.
+# * BUILD directory is set to default BUILD_DIR_BASE
+# * The "print_status" function both prints a status line to the log and keeps track of which test is running.
+# * Calling the "failure" function prints a failure message to the log and also adds to the list of failures to print at the end.
+# * The function "assert_built" tests for a file relative to the BUILD directory.
+# * The function "take_build_snapshot" can be paired with the functions "assert_rebuilt" and "assert_not_rebuilt" to compare file timestamps and verify if they were rebuilt or not since the snapshot was taken.
+#
+# To add a new test case, add it to the end of the run_tests function. Note that not all test cases do comprehensive cleanup
+# (although very invasive ones like appending CRLFs to all files take a copy of the esp-idf tree), however the clean_build_dir
+# function can be used to force-delete all files from the build output directory.
+
+# Set up some variables
+#
+# override ESP_IDF_TEMPLATE_GIT to point to a local dir if you're testing and want fast iterations
+[ -z ${ESP_IDF_TEMPLATE_GIT} ] && ESP_IDF_TEMPLATE_GIT=https://github.com/espressif/esp-idf-template.git
+
+# uncomment next line to produce a lot more debug output
+#export V=1
+
+export PATH="$IDF_PATH/tools:$PATH"  # for idf.py
+
+function run_tests()
+{
+    FAILURES=
+    STATUS="Starting"
+    print_status "Checking prerequisites"
+    [ -z ${IDF_PATH} ] && echo "IDF_PATH is not set. Need path to esp-idf installation." && exit 2
+
+    print_status "Cloning template from ${ESP_IDF_TEMPLATE_GIT}..."
+    git clone ${ESP_IDF_TEMPLATE_GIT} template
+    cd template
+    git checkout ${CI_BUILD_REF_NAME} || echo "Using esp-idf-template default branch..."
+
+    print_status "Try to clean fresh directory..."
+    idf.py fullclean || exit $?
+
+    # all relative to the build directory
+    BOOTLOADER_BINS="bootloader/bootloader.elf bootloader/bootloader.bin"
+    APP_BINS="app-template.elf app-template.bin"
+    PARTITION_BIN="partition_table/partition-table.bin"
+
+    print_status "Initial clean build"
+    # if build fails here, everything fails
+    idf.py build || exit $?
+
+    # check all the expected build artifacts from the clean build
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Updating component source file rebuilds component"
+    # touch a file & do a build
+    take_build_snapshot
+    touch ${IDF_PATH}/components/esp32/cpu_start.c
+    idf.py build || failure "Failed to partial build"
+    assert_rebuilt ${APP_BINS} esp32/libesp32.a esp32/CMakeFiles/esp32.dir/cpu_start.c.obj
+    assert_not_rebuilt lwip/liblwip.a freertos/libfreertos.a ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Bootloader source file rebuilds bootloader"
+    take_build_snapshot
+    touch ${IDF_PATH}/components/bootloader/subproject/main/bootloader_start.c
+    idf.py build || failure "Failed to partial build bootloader"
+    assert_rebuilt ${BOOTLOADER_BINS} bootloader/CMakeFiles/bootloader.elf.dir/main/bootloader_start.c.obj
+    assert_not_rebuilt ${APP_BINS} ${PARTITION_BIN}
+
+    print_status "Partition CSV file rebuilds partitions"
+    take_build_snapshot
+    touch ${IDF_PATH}/components/partition_table/partitions_singleapp.csv
+    idf.py build || failure "Failed to build partition table"
+    assert_rebuilt ${PARTITION_BIN}
+    assert_not_rebuilt app-template.bin app-template.elf ${BOOTLOADER_BINS}
+
+    print_status "Partial build doesn't compile anything by default"
+    take_build_snapshot
+    # verify no build files are refreshed by a partial make
+    ALL_BUILD_FILES=$(find ${BUILD} -type f | sed "s@${BUILD}/@@" | grep -v '^.')
+    idf.py build || failure "Partial build failed"
+    assert_not_rebuilt ${ALL_BUILD_FILES}
+
+    print_status "Moving BUILD_DIR_BASE out of tree"
+    clean_build_dir
+    OUTOFTREE_BUILD=${TESTDIR}/alt_build
+    idf.py -B "${OUTOFTREE_BUILD}" build || failure "Failed to build with out-of-tree build dir"
+    NEW_BUILD_FILES=$(find ${OUTOFREE_BUILD} -type f)
+    if [ -z "${NEW_BUILD_FILES}" ]; then
+        failure "No files found in new build directory!"
+    fi
+    DEFAULT_BUILD_FILES=$(find ${BUILD} -mindepth 1)
+    if [ -n "${DEFAULT_BUILD_FILES}" ]; then
+        failure "Some files were incorrectly put into the default build directory: ${DEFAULT_BUILD_FILES}"
+    fi
+
+    print_status "BUILD_DIR_BASE inside default build directory"
+    clean_build_dir
+    idf.py -B "build/subdirectory" build || failure "Failed to build with build dir as subdir"
+    NEW_BUILD_FILES=$(find ${BUILD}/subdirectory -type f)
+    if [ -z "${NEW_BUILD_FILES}" ]; then
+        failure "No files found in new build directory!"
+    fi
+
+    print_status "Can still clean build if all text files are CRLFs"
+    clean_build_dir
+    find . -path .git -prune -exec unix2dos {} \; # CRLFify template dir
+    # make a copy of esp-idf and CRLFify it
+    CRLF_ESPIDF=${TESTDIR}/esp-idf-crlf
+    mkdir -p ${CRLF_ESPIDF}
+    cp -r ${IDF_PATH}/* ${CRLF_ESPIDF}
+    # don't CRLFify executable files, as Linux will fail to execute them
+    find ${CRLF_ESPIDF} -name .git -prune -name build -prune -type f ! -perm 755 -exec unix2dos {} \;
+    IDF_PATH=${CRLF_ESPIDF} idf.py build || failure "Failed to build with CRLFs in source"
+    # do the same checks we do for the clean build
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Updating rom ld file should re-link app and bootloader"
+    clean_build_dir
+    idf.py build
+    take_build_snapshot
+    sleep 1  # ninja may ignore if the timestamp delta is too low
+    cp ${IDF_PATH}/components/esp32/ld/esp32.rom.ld .
+    echo "/* (Build test comment) */" >> ${IDF_PATH}/components/esp32/ld/esp32.rom.ld
+    tail ${IDF_PATH}/components/esp32/ld/esp32.rom.ld
+    idf.py build || failure "Failed to rebuild with modified linker script"
+    assert_rebuilt ${APP_BINS} ${BOOTLOADER_BINS}
+    mv esp32.rom.ld ${IDF_PATH}/components/esp32/ld/
+
+    print_status "Updating app-only ld file should only re-link app"
+    take_build_snapshot
+    cp ${IDF_PATH}/components/esp32/ld/esp32.common.ld .
+    sleep 1  # ninja may ignore if the timestamp delta is too low
+    echo "/* (Build test comment) */" >> ${IDF_PATH}/components/esp32/ld/esp32.common.ld
+    idf.py build || failure "Failed to rebuild with modified linker script"
+    assert_rebuilt ${APP_BINS}
+    assert_not_rebuilt ${BOOTLOADER_BINS}
+    mv esp32.common.ld ${IDF_PATH}/components/esp32/ld/
+
+    print_status "sdkconfig update triggers full recompile"
+    clean_build_dir
+    idf.py build
+    take_build_snapshot
+    # need to actually change config, or cmake is too smart to rebuild
+    sed -i s/CONFIG_FREERTOS_UNICORE=/CONFIG_FREERTOS_UNICORE=y/ sdkconfig
+    idf.py build
+    # check the sdkconfig.h file was rebuilt
+    assert_rebuilt sdkconfig.h
+    # pick one each of .c, .cpp, .S that #includes sdkconfig.h
+    # and therefore should rebuild
+    assert_rebuilt newlib/CMakeFiles/newlib.dir/syscall_table.c.obj
+    assert_rebuilt nvs_flash/CMakeFiles/nvs_flash.dir/src/nvs_api.cpp.obj
+    assert_rebuilt freertos/CMakeFiles/freertos.dir/xtensa_vectors.S.obj
+
+    print_status "Updating project CMakeLists.txt triggers full recompile"
+    clean_build_dir
+    idf.py build
+    take_build_snapshot
+    # Need to actually change the build config, or CMake won't do anything
+    sed -i 's/^project(/add_compile_options("-DUSELESS_MACRO_DOES_NOTHING=1")\nproject\(/' CMakeLists.txt
+    idf.py build
+    # similar to previous test
+    assert_rebuilt newlib/CMakeFiles/newlib.dir/syscall_table.c.obj
+    assert_rebuilt nvs_flash/CMakeFiles/nvs_flash.dir/src/nvs_api.cpp.obj
+    assert_rebuilt freertos/CMakeFiles/freertos.dir/xtensa_vectors.S.obj
+
+    print_status "All tests completed"
+    if [ -n "${FAILURES}" ]; then
+        echo "Some failures were detected:"
+        echo -e "${FAILURES}"
+        exit 1
+    else
+        echo "Build tests passed."
+    fi
+}
+
+function print_status()
+{
+    echo "******** $1"
+    STATUS="$1"
+}
+
+function failure()
+{
+    echo "!!!!!!!!!!!!!!!!!!!"
+    echo "FAILURE: $1"
+    echo "!!!!!!!!!!!!!!!!!!!"
+    FAILURES="${FAILURES}${STATUS} :: $1\n"
+}
+
+TESTDIR=${PWD}/build_system_tests_$$
+mkdir -p ${TESTDIR}
+# set NOCLEANUP=1 if you want to keep the test directory around
+# for post-mortem debugging
+[ -z ${NOCLEANUP} ] && trap "rm -rf ${TESTDIR}" EXIT KILL
+
+SNAPSHOT=${TESTDIR}/snapshot
+BUILD=${TESTDIR}/template/build
+
+
+# copy all the build output to a snapshot directory
+function take_build_snapshot()
+{
+    rm -rf ${SNAPSHOT}
+    cp -ap ${TESTDIR}/template/build ${SNAPSHOT}
+}
+
+# verify that all the arguments are present in the build output directory
+function assert_built()
+{
+    until [ -z "$1" ]; do
+        if [ ! -f "${BUILD}/$1" ]; then
+            failure "File $1 should be in the build output directory"
+        fi
+        shift
+    done
+}
+
+# Test if a file has been rebuilt.
+function file_was_rebuilt()
+{
+    # can't use [ a -ot b ] here as -ot only gives second resolution
+    # but stat -c %y seems to be microsecond at least for tmpfs, ext4..
+    if [ "$(stat -c %y ${SNAPSHOT}/$1)" != "$(stat -c %y ${BUILD}/$1)" ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# verify all the arguments passed in were rebuilt relative to the snapshot
+function assert_rebuilt()
+{
+    until [ -z "$1" ]; do
+        assert_built "$1"
+        if [ ! -f "${SNAPSHOT}/$1" ]; then
+            failure "File $1 should be in original build snapshot"
+        fi
+        if ! file_was_rebuilt "$1"; then
+            failure "File $1 should have been rebuilt"
+        fi
+        shift
+    done
+}
+
+# verify all the arguments are in the build directory & snapshot,
+# but were not rebuilt
+function assert_not_rebuilt()
+{
+    until [ -z "$1" ]; do
+        assert_built "$1"
+        if [ ! -f "${SNAPSHOT}/$1" ]; then
+            failure "File $1 should be in snapshot build directory"
+        fi
+        if file_was_rebuilt "$1"; then
+            failure "File $1 should not have been rebuilt"
+        fi
+        shift
+    done
+}
+
+# do a "clean" that doesn't depend on idf.py
+function clean_build_dir()
+{
+    rm -rf --preserve-root ${BUILD}/* ${BUILD}/.*
+}
+
+cd ${TESTDIR}
+run_tests
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index e91385180..791e3fbfa 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -147,28 +147,31 @@ function(file_append_line file line)
     file(APPEND "${file}" "${line}${line_ending}")
 endfunction()
 
-# Add a linker script to the target, including a link-time dependency
+# Add one or more linker scripts to the target, including a link-time dependency
 #
 # Automatically adds a -L search path for the containing directory (if found),
 # and then adds -T with the filename only. This allows INCLUDE directives to be
 # used to include other linker scripts in the same directory.
-function(target_linker_script target scriptfile)
-    get_filename_component(abs_script "${scriptfile}" ABSOLUTE)
+function(target_linker_script target)
+    foreach(scriptfile ${ARGN})
+        get_filename_component(abs_script "${scriptfile}" ABSOLUTE)
+        message(STATUS "Adding linker script ${abs_script}")
 
-    get_filename_component(search_dir "${abs_script}" DIRECTORY)
-    get_filename_component(scriptname "${abs_script}" NAME)
+        get_filename_component(search_dir "${abs_script}" DIRECTORY)
+        get_filename_component(scriptname "${abs_script}" NAME)
 
-    get_target_property(link_libraries "${target}" LINK_LIBRARIES)
-    list(FIND "${link_libraries}" "-L ${search_dir}" found_search_dir)
-    if(found_search_dir EQUAL "-1")  # not already added as a search path
-        target_link_libraries("${target}" "-L ${search_dir}")
-    endif()
+        get_target_property(link_libraries "${target}" LINK_LIBRARIES)
+        list(FIND "${link_libraries}" "-L ${search_dir}" found_search_dir)
+        if(found_search_dir EQUAL "-1")  # not already added as a search path
+            target_link_libraries("${target}" "-L ${search_dir}")
+        endif()
 
-    target_link_libraries("${target}" "-T ${scriptname}")
+        target_link_libraries("${target}" "-T ${scriptname}")
 
-    # Note: In ESP-IDF, most targets are libraries and libary LINK_DEPENDS don't propagate to
-    # executable(s) the library is linked to. This is done manually in components.cmake.
-    set_property(TARGET "${target}" APPEND PROPERTY LINK_DEPENDS "${abs_script}")
+        # Note: In ESP-IDF, most targets are libraries and libary LINK_DEPENDS don't propagate to
+        # executable(s) the library is linked to. This is done manually in components.cmake.
+        set_property(TARGET "${target}" APPEND PROPERTY LINK_DEPENDS "${abs_script}")
+    endforeach()
 endfunction()
 
 # Convert a CMake list to a JSON list and store it in a variable

From 381be65472f9cd3dfaec5be4992293376ceb16f2 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 18 Apr 2018 17:54:28 +1000
Subject: [PATCH 046/112] cmake: Build all examples in CI

Includes some fixes for compile errors/warnings in examples.
---
 .gitlab-ci.yml                                |   6 +
 components/bt/CMakeLists.txt                  | 131 ++++++-------
 components/lwip/CMakeLists.txt                |   3 +
 components/partition_table/CMakeLists.txt     |   2 +-
 docs/en/api-guides/build-system-cmake.rst     |   6 +
 examples/bluetooth/a2dp_sink/CMakeLists.txt   |   0
 examples/bluetooth/a2dp_sink/Makefile         |   0
 examples/bluetooth/a2dp_sink/README.md        |   0
 examples/bluetooth/a2dp_source/CMakeLists.txt |   0
 examples/bluetooth/a2dp_source/Makefile       |   0
 examples/bluetooth/a2dp_source/README.md      |   0
 .../bluetooth/a2dp_source/main/component.mk   |   0
 .../throughput_client/CMakeLists.txt          |  10 +
 .../throughput_server/CMakeLists.txt          |  10 +
 examples/bluetooth/bt_discovery/Makefile      |   0
 examples/bluetooth/bt_discovery/README.rst    |   0
 .../bluetooth/bt_discovery/main/component.mk  |   0
 .../bt_spp_vfs_acceptor/CMakeLists.txt        |  10 +
 .../bt_spp_vfs_initiator/CMakeLists.txt       |  10 +
 .../peripherals/spi_master/CMakeLists.txt     |  11 +-
 examples/wifi/iperf/components/CMakeLists.txt |   2 +
 tools/ci/build_examples_cmake.sh              | 173 ++++++++++++++++++
 tools/cmake/scripts/data_file_embed_asm.cmake |   2 +-
 23 files changed, 310 insertions(+), 66 deletions(-)
 mode change 100755 => 100644 examples/bluetooth/a2dp_sink/CMakeLists.txt
 mode change 100755 => 100644 examples/bluetooth/a2dp_sink/Makefile
 mode change 100755 => 100644 examples/bluetooth/a2dp_sink/README.md
 mode change 100755 => 100644 examples/bluetooth/a2dp_source/CMakeLists.txt
 mode change 100755 => 100644 examples/bluetooth/a2dp_source/Makefile
 mode change 100755 => 100644 examples/bluetooth/a2dp_source/README.md
 mode change 100755 => 100644 examples/bluetooth/a2dp_source/main/component.mk
 create mode 100644 examples/bluetooth/ble_throughput/throughput_client/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_throughput/throughput_server/CMakeLists.txt
 mode change 100755 => 100644 examples/bluetooth/bt_discovery/Makefile
 mode change 100755 => 100644 examples/bluetooth/bt_discovery/README.rst
 mode change 100755 => 100644 examples/bluetooth/bt_discovery/main/component.mk
 create mode 100644 examples/bluetooth/bt_spp_vfs_acceptor/CMakeLists.txt
 create mode 100644 examples/bluetooth/bt_spp_vfs_initiator/CMakeLists.txt
 create mode 100755 tools/ci/build_examples_cmake.sh

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f0a5fd821..be3bb0ba0 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -177,6 +177,12 @@ build_esp_idf_tests:
     # build some of examples
     - mkdir -p ${LOG_PATH}
     - ${IDF_PATH}/tools/ci/build_examples.sh "${CI_JOB_NAME}"
+    # and again, with cmake!
+    - rm -rf ../build_examples_cmake
+    - mkdir ../build_examples_cmake
+    - cd ../build_examples_cmake
+    - mkdir -p ${LOG_PATH}_cmake
+    - LOG_PATH=${LOG_PATH}_cmake ${IDF_PATH}/tools/ci/build_examples_cmake.sh "${CI_JOB_NAME}"
 
 build_examples_00:
   <<: *build_examples_template
diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index c2134be8f..2a0941379 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -5,73 +5,78 @@ if(CONFIG_BT_ENABLED)
 
     if(CONFIG_BLUEDROID_ENABLED)
 
-        list(APPEND COMPONENT_ADD_INCLUDEDIRS
+        list(APPEND COMPONENT_PRIV_INCLUDEDIRS
             bluedroid/bta/include
-		    bluedroid/bta/sys/include
-		    bluedroid/btcore/include
-		    bluedroid/device/include
-		    bluedroid/hci/include
-		    bluedroid/osi/include
-		    bluedroid/external/sbc/decoder/include
-		    bluedroid/external/sbc/encoder/include
-		    bluedroid/btc/profile/esp/blufi/include
-		    bluedroid/btc/profile/esp/include
-		    bluedroid/btc/profile/std/a2dp/include
-		    bluedroid/btc/profile/std/include
-		    bluedroid/btc/include
-		    bluedroid/stack/gap/include
-		    bluedroid/stack/gatt/include
-		    bluedroid/stack/l2cap/include
-		    bluedroid/stack/sdp/include
-		    bluedroid/stack/smp/include
-		    bluedroid/stack/avct/include
-		    bluedroid/stack/avrc/include
-		    bluedroid/stack/avdt/include
-		    bluedroid/stack/a2dp/include
-		    bluedroid/stack/rfcomm/include
-		    bluedroid/stack/include
-		    bluedroid/api/include
-		    bluedroid/include
-            )
+            bluedroid/bta/ar/include
+            bluedroid/bta/av/include
+            bluedroid/bta/dm/include
+            bluedroid/bta/gatt/include
+            bluedroid/bta/hh/include
+            bluedroid/bta/jv/include
+            bluedroid/bta/sdp/include
+            bluedroid/bta/sys/include
+            bluedroid/device/include
+            bluedroid/hci/include
+            bluedroid/osi/include
+            bluedroid/external/sbc/decoder/include
+            bluedroid/external/sbc/encoder/include
+            bluedroid/btc/profile/esp/blufi/include
+            bluedroid/btc/profile/esp/include
+            bluedroid/btc/profile/std/a2dp/include
+            bluedroid/btc/profile/std/include
+            bluedroid/btc/include
+            bluedroid/stack/btm/include
+            bluedroid/stack/gap/include
+            bluedroid/stack/gatt/include
+            bluedroid/stack/l2cap/include
+            bluedroid/stack/sdp/include
+            bluedroid/stack/smp/include
+            bluedroid/stack/avct/include
+            bluedroid/stack/avrc/include
+            bluedroid/stack/avdt/include
+            bluedroid/stack/a2dp/include
+            bluedroid/stack/rfcomm/include
+            bluedroid/stack/include
+            bluedroid/common/include)
+
+        list(APPEND COMPONENT_ADD_INCLUDEDIRS bluedroid/api/include/api)
 
         list(APPEND COMPONENT_SRCDIRS
             bluedroid/bta/dm
-		    bluedroid/bta/gatt
-		    bluedroid/bta/hh
-		    bluedroid/bta/sdp
-		    bluedroid/bta/av
-		    bluedroid/bta/ar
-		    bluedroid/bta/sys
-		    bluedroid/bta/jv
-		    bluedroid/btcore
-		    bluedroid/btif
-		    bluedroid/device
-		    bluedroid/hci
-		    bluedroid/main
-		    bluedroid/osi
-		    bluedroid/external/sbc/decoder/srce
-		    bluedroid/external/sbc/encoder/srce
-		    bluedroid/btc/core
-		    bluedroid/btc/profile/esp/blufi
-		    bluedroid/btc/profile/std/gap
-		    bluedroid/btc/profile/std/gatt
-		    bluedroid/btc/profile/std/a2dp
-		    bluedroid/btc/profile/std/avrc
-		    bluedroid/btc/profile/std/spp
-		    bluedroid/stack/btm
-		    bluedroid/stack/btu
-		    bluedroid/stack/gap
-		    bluedroid/stack/gatt
-		    bluedroid/stack/hcic
-		    bluedroid/stack/l2cap
-		    bluedroid/stack/sdp
-		    bluedroid/stack/smp
-		    bluedroid/stack/avct
-		    bluedroid/stack/avrc
-		    bluedroid/stack/avdt
-		    bluedroid/stack/a2dp
-		    bluedroid/stack/rfcomm
-		    bluedroid/api
+            bluedroid/bta/gatt
+            bluedroid/bta/hh
+            bluedroid/bta/sdp
+            bluedroid/bta/av
+            bluedroid/bta/ar
+            bluedroid/bta/sys
+            bluedroid/bta/jv
+            bluedroid/device
+            bluedroid/hci
+            bluedroid/main
+            bluedroid/osi
+            bluedroid/external/sbc/decoder/srce
+            bluedroid/external/sbc/encoder/srce
+            bluedroid/btc/core
+            bluedroid/btc/profile/esp/blufi
+            bluedroid/btc/profile/std/gap
+            bluedroid/btc/profile/std/gatt
+            bluedroid/btc/profile/std/a2dp
+            bluedroid/btc/profile/std/avrc
+            bluedroid/btc/profile/std/spp
+            bluedroid/stack/btm
+            bluedroid/stack/btu
+            bluedroid/stack/gap
+            bluedroid/stack/gatt
+            bluedroid/stack/hcic
+            bluedroid/stack/l2cap
+            bluedroid/stack/sdp
+            bluedroid/stack/smp
+            bluedroid/stack/avct
+            bluedroid/stack/avrc
+            bluedroid/stack/avdt
+            bluedroid/stack/a2dp
+            bluedroid/stack/rfcomm
+            bluedroid/api
             )
     endif()
 endif()
diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
index 03deae436..d44424735 100644
--- a/components/lwip/CMakeLists.txt
+++ b/components/lwip/CMakeLists.txt
@@ -36,3 +36,6 @@ set_source_files_properties(apps/dhcpserver.c
     PROPERTIES COMPILE_FLAGS
     "-Wno-unused-variable -Wno-unused-but-set-variable -Wno-type-limits"
     )
+set_source_files_properties(netif/ppp/pppos.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-type-limits)
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index cde193dce..72ef78ff1 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -6,7 +6,7 @@ register_config_only_component()
 #
 if(CONFIG_PARTITION_TABLE_CUSTOM)
     # Custom filename expands any path relative to the project
-    get_filename_component(partition_csv "${CONFIG_PARTITION_TABLE_CUSTOM}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+    get_filename_component(partition_csv "${CONFIG_PARTITION_TABLE_FILENAME}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
 else()
     # Other .csv files are always in the component directory
     set(partition_csv "${CMAKE_CURRENT_SOURCE_DIR}/${CONFIG_PARTITION_TABLE_FILENAME}")
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index 03eb0c206..717589634 100644
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -586,6 +586,12 @@ The file's contents will be added to the .rodata section in flash, and are avail
 
 The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
 
+To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
+
+  target_add_binary_data(myproject.elf "main/data.bin" TEXT)
+
+Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
+
 For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
 
 
diff --git a/examples/bluetooth/a2dp_sink/CMakeLists.txt b/examples/bluetooth/a2dp_sink/CMakeLists.txt
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_sink/Makefile b/examples/bluetooth/a2dp_sink/Makefile
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_sink/README.md b/examples/bluetooth/a2dp_sink/README.md
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_source/CMakeLists.txt b/examples/bluetooth/a2dp_source/CMakeLists.txt
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_source/Makefile b/examples/bluetooth/a2dp_source/Makefile
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_source/README.md b/examples/bluetooth/a2dp_source/README.md
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/a2dp_source/main/component.mk b/examples/bluetooth/a2dp_source/main/component.mk
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/ble_throughput/throughput_client/CMakeLists.txt b/examples/bluetooth/ble_throughput/throughput_client/CMakeLists.txt
new file mode 100644
index 000000000..c557a916e
--- /dev/null
+++ b/examples/bluetooth/ble_throughput/throughput_client/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/example_ble_client_throughput.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(throughput_client_demo)
diff --git a/examples/bluetooth/ble_throughput/throughput_server/CMakeLists.txt b/examples/bluetooth/ble_throughput/throughput_server/CMakeLists.txt
new file mode 100644
index 000000000..8d3bd0cbb
--- /dev/null
+++ b/examples/bluetooth/ble_throughput/throughput_server/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/example_ble_server_throughput.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(throughput_server_demo)
diff --git a/examples/bluetooth/bt_discovery/Makefile b/examples/bluetooth/bt_discovery/Makefile
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/bt_discovery/README.rst b/examples/bluetooth/bt_discovery/README.rst
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/bt_discovery/main/component.mk b/examples/bluetooth/bt_discovery/main/component.mk
old mode 100755
new mode 100644
diff --git a/examples/bluetooth/bt_spp_vfs_acceptor/CMakeLists.txt b/examples/bluetooth/bt_spp_vfs_acceptor/CMakeLists.txt
new file mode 100644
index 000000000..b37ab5f68
--- /dev/null
+++ b/examples/bluetooth/bt_spp_vfs_acceptor/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/example_spp_vfs_acceptor_demo.c
+    main/spp_task.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_spp_vfs_acceptor_demo)
diff --git a/examples/bluetooth/bt_spp_vfs_initiator/CMakeLists.txt b/examples/bluetooth/bt_spp_vfs_initiator/CMakeLists.txt
new file mode 100644
index 000000000..94c7b230d
--- /dev/null
+++ b/examples/bluetooth/bt_spp_vfs_initiator/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/example_spp_vfs_initiator_demo.c
+    main/spp_task.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_spp_vfs_initiator_demo)
diff --git a/examples/peripherals/spi_master/CMakeLists.txt b/examples/peripherals/spi_master/CMakeLists.txt
index e7640d84f..d27864187 100644
--- a/examples/peripherals/spi_master/CMakeLists.txt
+++ b/examples/peripherals/spi_master/CMakeLists.txt
@@ -2,7 +2,16 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
-set(MAIN_SRCS main/spi_master_example_main.c)
+set(MAIN_SRCS
+    main/spi_master_example_main.c
+    main/pretty_effect.c
+    main/decode_image.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(spi_master)
+
+# Embed the image into the final binary
+#
+# (If this was a component, we would set COMPONENT_EMBED_TXTFILES here.)
+target_add_binary_data(spi_master.elf
+    "main/image.jpg" BINARY)
diff --git a/examples/wifi/iperf/components/CMakeLists.txt b/examples/wifi/iperf/components/CMakeLists.txt
index 74bb26787..352403c41 100644
--- a/examples/wifi/iperf/components/CMakeLists.txt
+++ b/examples/wifi/iperf/components/CMakeLists.txt
@@ -2,4 +2,6 @@ set(COMPONENT_ADD_INCLUDEDIRS .)
 
 set(COMPONENT_SRCDIRS .)
 
+set(COMPONENT_PRIV_REQUIRES lwip)
+
 register_component()
diff --git a/tools/ci/build_examples_cmake.sh b/tools/ci/build_examples_cmake.sh
new file mode 100755
index 000000000..e4f728cbd
--- /dev/null
+++ b/tools/ci/build_examples_cmake.sh
@@ -0,0 +1,173 @@
+#!/bin/bash
+#
+# Build all examples from the examples directory, out of tree to
+# ensure they can run when copied to a new directory.
+#
+# Runs as part of CI process.
+#
+# Assumes PWD is an out-of-tree build directory, and will copy examples
+# to individual subdirectories, one by one.
+#
+#
+# Without arguments it just builds all examples
+#
+# With one argument <JOB_NAME> it builds part of the examples. This is a useful for
+#   parallel execution in CI.
+#   <JOB_NAME> must look like this:
+#               <some_text_label>_<num>
+#   It scans .gitlab-ci.yaml to count number of jobs which have name "<some_text_label>_<num>"
+#   It scans the filesystem to count all examples
+#   Based on this, it decides to run qa set of examples.
+#
+
+# -----------------------------------------------------------------------------
+# Safety settings (see https://gist.github.com/ilg-ul/383869cbb01f61a51c4d).
+
+if [[ ! -z ${DEBUG_SHELL} ]]
+then
+  set -x # Activate the expand mode if DEBUG is anything but empty.
+fi
+
+set -o errexit # Exit if command failed.
+set -o pipefail # Exit if pipe failed.
+
+# Remove the initial space and instead use '\n'.
+IFS=$'\n\t'
+
+export PATH="$IDF_PATH/tools:$PATH"  # for idf.py
+
+# -----------------------------------------------------------------------------
+
+die() {
+    echo "${1:-"Unknown Error"}" 1>&2
+    exit 1
+}
+
+[ -z ${IDF_PATH} ] && die "IDF_PATH is not set"
+[ -z ${LOG_PATH} ] && die "LOG_PATH is not set"
+[ -d ${LOG_PATH} ] || mkdir -p ${LOG_PATH}
+
+set -o nounset # Exit if variable not set.
+
+echo "build_examples running in ${PWD}"
+
+# only 0 or 1 arguments
+[ $# -le 1 ] || die "Have to run as $(basename $0) [<JOB_NAME>]"
+
+export BATCH_BUILD=1
+export V=0 # only build verbose if there's an error
+
+shopt -s lastpipe # Workaround for Bash to use variables in loops (http://mywiki.wooledge.org/BashFAQ/024)
+
+RESULT=0
+FAILED_EXAMPLES=""
+RESULT_ISSUES=22  # magic number result code for issues found
+LOG_SUSPECTED=${LOG_PATH}/common_log.txt
+touch ${LOG_SUSPECTED}
+
+EXAMPLE_PATHS=$( find ${IDF_PATH}/examples/ -type f -name CMakeLists.txt | grep -v "/components/" | sort )
+
+if [ $# -eq 0 ]
+then
+    START_NUM=0
+    END_NUM=999
+else
+    JOB_NAME=$1
+
+    # parse text prefix at the beginning of string 'some_your_text_NUM'
+    # (will be 'some_your_text' without last '_')
+    JOB_PATTERN=$( echo ${JOB_NAME} | sed -n -r 's/^(.*)_[0-9]+$/\1/p' )
+    [ -z ${JOB_PATTERN} ] && die "JOB_PATTERN is bad"
+
+    # parse number 'NUM' at the end of string 'some_your_text_NUM'
+    JOB_NUM=$( echo ${JOB_NAME} | sed -n -r 's/^.*_([0-9]+)$/\1/p' )
+    [ -z ${JOB_NUM} ] && die "JOB_NUM is bad"
+
+    # count number of the jobs
+    NUM_OF_JOBS=$( grep -c -E "^${JOB_PATTERN}_[0-9]+:$" "${IDF_PATH}/.gitlab-ci.yml" )
+    [ -z ${NUM_OF_JOBS} ] && die "NUM_OF_JOBS is bad"
+
+    # count number of examples
+    NUM_OF_EXAMPLES=$(echo ${EXAMPLE_PATHS} | wc -l )
+    [ -z ${NUM_OF_EXAMPLES} ] && die "NUM_OF_EXAMPLES is bad"
+
+    # separate intervals
+    #57 / 5 == 12
+    NUM_OF_EX_PER_JOB=$(( (${NUM_OF_EXAMPLES} + ${NUM_OF_JOBS} - 1) / ${NUM_OF_JOBS} ))
+    [ -z ${NUM_OF_EX_PER_JOB} ] && die "NUM_OF_EX_PER_JOB is bad"
+
+    # ex.: [0; 12); [12; 24); [24; 36); [36; 48); [48; 60)
+    START_NUM=$(( ${JOB_NUM} * ${NUM_OF_EX_PER_JOB} ))
+    [ -z ${START_NUM} ] && die "START_NUM is bad"
+
+    END_NUM=$(( (${JOB_NUM} + 1) * ${NUM_OF_EX_PER_JOB} ))
+    [ -z ${END_NUM} ] && die "END_NUM is bad"
+fi
+
+build_example () {
+    local ID=$1
+    shift
+    local CMAKELISTS=$1
+    shift
+
+    local EXAMPLE_DIR=$(dirname "${CMAKELISTS}")
+    local EXAMPLE_NAME=$(basename "${EXAMPLE_DIR}")
+
+    echo "Building ${EXAMPLE_NAME} as ${ID}..."
+    mkdir -p "example_builds/${ID}"
+    cp -r "${EXAMPLE_DIR}" "example_builds/${ID}"
+    pushd "example_builds/${ID}/${EXAMPLE_NAME}"
+        # be stricter in the CI build than the default IDF settings
+        export EXTRA_CFLAGS="-Werror -Werror=deprecated-declarations"
+        export EXTRA_CXXFLAGS=${EXTRA_CFLAGS}
+
+        # build non-verbose first
+        local BUILDLOG=${LOG_PATH}/ex_${ID}_log.txt
+        touch ${BUILDLOG}
+
+        idf.py fullclean >>${BUILDLOG} 2>&1 &&
+        idf.py build >>${BUILDLOG} 2>&1 &&
+        cp build/flash_project_args build/download.config || # backwards compatible download.config filename
+        {
+            RESULT=$?; FAILED_EXAMPLES+=" ${EXAMPLE_NAME}" ;
+        }
+
+        cat ${BUILDLOG}
+    popd
+
+    grep -i "error\|warning" "${BUILDLOG}" 2>&1 | grep -v "error.c.obj" >> "${LOG_SUSPECTED}" || :
+}
+
+EXAMPLE_NUM=0
+
+for EXAMPLE_PATH in ${EXAMPLE_PATHS}
+do
+    if [[ $EXAMPLE_NUM -lt $START_NUM || $EXAMPLE_NUM -ge $END_NUM ]]
+    then
+        EXAMPLE_NUM=$(( $EXAMPLE_NUM + 1 ))
+        continue
+    fi
+    echo ">>> example [ ${EXAMPLE_NUM} ] - $EXAMPLE_PATH"
+
+    build_example "${EXAMPLE_NUM}" "${EXAMPLE_PATH}"
+
+    EXAMPLE_NUM=$(( $EXAMPLE_NUM + 1 ))
+done
+
+# show warnings
+echo -e "\nFound issues:"
+
+#       Ignore the next messages:
+# "error.o" or "-Werror" in compiler's command line
+# "reassigning to symbol" or "changes choice state" in sdkconfig
+sort -u "${LOG_SUSPECTED}" | \
+grep -v "library/error.o\|\ -Werror\|reassigning to symbol\|changes choice state" \
+    && RESULT=$RESULT_ISSUES \
+    || echo -e "\tNone"
+
+[ -z ${FAILED_EXAMPLES} ] || echo -e "\nThere are errors in the next examples: $FAILED_EXAMPLES"
+[ $RESULT -eq 0 ] || echo -e "\nFix all warnings and errors above to pass the test!"
+
+echo -e "\nReturn code = $RESULT"
+
+exit $RESULT
diff --git a/tools/cmake/scripts/data_file_embed_asm.cmake b/tools/cmake/scripts/data_file_embed_asm.cmake
index 76a1fe298..71329ade5 100644
--- a/tools/cmake/scripts/data_file_embed_asm.cmake
+++ b/tools/cmake/scripts/data_file_embed_asm.cmake
@@ -8,7 +8,7 @@
 #
 # Set variables DATA_FILE, SOURCE_FILE, FILE_TYPE when running this.
 #
-# If FILE_TYPE is set to STRING, a null byte is appended to DATA_FILE's contents
+# If FILE_TYPE is set to TEXT, a null byte is appended to DATA_FILE's contents
 # before SOURCE_FILE is created.
 #
 # If FILE_TYPE is unset (or any other value), DATA_FILE is copied

From 99e02d4e42a4e549a660bb4ba1d037b5ad2083b2 Mon Sep 17 00:00:00 2001
From: Angus Gratton <gus@projectgus.com>
Date: Tue, 24 Apr 2018 18:23:57 +1000
Subject: [PATCH 047/112] windows: New ESP-IDF Tools Installer

Working on 64-bit Windows only due to Ninja binary.
---
 .gitignore                                    |   6 +
 .../add-idf_path-to-profile-cmake.rst         |   2 +-
 docs/en/get-started/index-cmake.rst           |   3 +-
 docs/en/get-started/windows-setup-cmake.rst   |  70 ++----
 .../windows-setup-scratch-cmake.rst           |  85 +++++++
 tools/windows/tool_setup/build_installer.sh   |  28 +++
 tools/windows/tool_setup/idf_tool_setup.iss   | 225 ++++++++++++++++++
 7 files changed, 372 insertions(+), 47 deletions(-)
 create mode 100644 docs/en/get-started/windows-setup-scratch-cmake.rst
 create mode 100755 tools/windows/tool_setup/build_installer.sh
 create mode 100644 tools/windows/tool_setup/idf_tool_setup.iss

diff --git a/.gitignore b/.gitignore
index 8448bf404..7cbe54130 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,9 @@ examples/protocols/aws_iot/*/main/certs/*.pem.*
 *.gcno
 coverage.info
 coverage_report/
+
+# Windows tools installer build
+tools/windows/tool_setup/.*
+tools/windows/tool_setup/input
+tools/windows/tool_setup/dl
+tools/windows/tool_setup/Output
diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
index cdb120736..0f5cbcef1 100644
--- a/docs/en/get-started/add-idf_path-to-profile-cmake.rst
+++ b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
@@ -19,7 +19,7 @@ To preserve setting of these variables between system restarts, add them to the
 Windows
 -------
 
-To edit Environment Variables on Windows 10, search for "Edit Environment Vartiables" under the Start menu.
+To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
 
 On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
 
diff --git a/docs/en/get-started/index-cmake.rst b/docs/en/get-started/index-cmake.rst
index 4eb2ef12f..9bc7f0773 100644
--- a/docs/en/get-started/index-cmake.rst
+++ b/docs/en/get-started/index-cmake.rst
@@ -138,8 +138,9 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``.
 Setup Paths for ESP-IDF
 =======================
 
-The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile-cmake`.
+The build system and tools find ESP-IDF using the ``IDF_PATH`` environment variable, or by running the ``idf.py`` utility in the tools/ directory of the esp-idf source.
 
+These paths should be set up as environment variables on your computer, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` and updating ``PATH`` in your user profile. To do so, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile-cmake`.
 
 .. _get-started-start-project-cmake:
 
diff --git a/docs/en/get-started/windows-setup-cmake.rst b/docs/en/get-started/windows-setup-cmake.rst
index ee9ebf3b3..8c4ac6db3 100644
--- a/docs/en/get-started/windows-setup-cmake.rst
+++ b/docs/en/get-started/windows-setup-cmake.rst
@@ -6,65 +6,46 @@ Setup for cmake on Windows
       The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<windows-setup>`.
 
 .. note::
-   Windows support in particular currently requires more manual installation of tools and setup of system Path than is planned for final release.
+      The CMake-based build system is only supported on 64-bit versions of Windows.
 
 Introduction
 ============
 
-Unlike the conventional ESP-IDF make-based build environment, cmake does not require a GNU-compatible environment for building. You can build with cmake from Windows Command Prompt, or from an IDE with cmake support.
+Unlike the conventional ESP-IDF make-based build environment, cmake does not require MSYS2 or another GNU-compatible environment (like Cygwin) for building. You can build with cmake from Windows Command Prompt, or from an IDE with cmake support.
 
-Tools
-=====
+ESP-IDF Tools Installer
+=======================
 
-The following software packages need to be installed:
+The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
 
-cmake
-^^^^^
+https://dl.espressif.com/esp-idf-tools-setup-1.0.exe
 
-Download the latest stable release of CMake_ for Windows and run the installer.
+The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and mconf configuration tool. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
 
-When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
+By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
+
+Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
+
+Installing Git
+==============
+
+The ESP-IDF tools does not include Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a Git command line for Windows (along with the Git-Bash terminal) from https://gitforwindows.org/.
+
+If you prefer to use a different graphical Git client, then you can install one of these instead - you will need to translate the Git commands in the getting started guide for use with your chosen Git client.
 
 
-Ninja build
-^^^^^^^^^^^
+Related Documents
+=================
 
-Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
+.. toctree::
+    :maxdepth: 1
 
-The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory on your PATH.
+    windows-setup-scratch-cmake
 
-An easy directory to place ``ninja.exe`` is the CMake executable directory, as this is already on the PATH. This directory will be something like ``C:\Program Files\CMake\bin`` (look for the file ``cmake.exe`` in this directory to know it's the correct one).
-
-Python 2.x
-^^^^^^^^^^
-
-Download the latest Python_ 2.7 for Windows installer, and run it.
-
-The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
-
-Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
-
-  pip install pyserial
-
-
-Toolchain Setup
-===============
-
-Download the precompiled Windows toolchain from dl.espressif.com:
-
-https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
-
-Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
-
-Next, you need to add the ``bin`` subdirectory to your PATH. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
-
-Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
-
-Double-click the ``Path`` variable (either User or System Path, depending if you want other users to use the toolchain.) Go to the end of the value, and append ``;C:\Program Files\xtensa-esp32-elf\bin`` (or whatever the path to your toolchain ``bin`` directory is).
-
-.. note::
-   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
+Manual Installation
+^^^^^^^^^^^^^^^^^^^
 
+Optionall
 
 Next Steps
 ==========
@@ -74,5 +55,4 @@ To carry on with development environment setup, proceed to section :ref:`get-sta
 
 .. _cmake: https://cmake.org/download/
 .. _ninja: https://ninja-build.org/
-.. _ninja-dl: https://github.com/ninja-build/ninja/releases
 .. _Python: https://www.python.org/downloads/windows/
diff --git a/docs/en/get-started/windows-setup-scratch-cmake.rst b/docs/en/get-started/windows-setup-scratch-cmake.rst
new file mode 100644
index 000000000..a4e12ae5c
--- /dev/null
+++ b/docs/en/get-started/windows-setup-scratch-cmake.rst
@@ -0,0 +1,85 @@
+***************************************
+Setup for cmake on Windows from Scratch
+***************************************
+
+Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`ESP-IDF Tools Installer <windows-setup-cmake>` automates the steps mentioned below.
+
+To quickly setup the toolchain and other tools in standard way, using the installer, proceed to section :doc:`windows-setup-cmake`.
+
+Note that, unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer.
+
+Tools
+=====
+
+cmake
+^^^^^
+
+Download the latest stable release of CMake_ for Windows and run the installer.
+
+When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
+
+Ninja build
+^^^^^^^^^^^
+
+.. note::
+    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
+
+Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
+
+The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>` (or you can choose a directory which is already on your Path).
+
+
+Python 2.x
+^^^^^^^^^^
+
+Download the latest Python_ 2.7 for Windows installer, and run it.
+
+The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
+
+Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
+
+  pip install pyserial
+
+MConf
+^^^^^
+
+Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page <mconf>`.
+
+This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`.
+
+Toolchain Setup
+===============
+
+Download the precompiled Windows toolchain from dl.espressif.com:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+
+Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
+
+Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
+
+.. note::
+   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
+
+
+.. _add-directory-windows-path:
+
+Adding Directory to Path
+========================
+
+To add any new directory to your Windows Path environment variable:
+
+Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
+
+Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+
+.. _cmake: https://cmake.org/download/
+.. _ninja: https://ninja-build.org/
+.. _ninja-dl: https://github.com/ninja-build/ninja/releases
+.. _Python: https://www.python.org/downloads/windows/
diff --git a/tools/windows/tool_setup/build_installer.sh b/tools/windows/tool_setup/build_installer.sh
new file mode 100755
index 000000000..8733629b6
--- /dev/null
+++ b/tools/windows/tool_setup/build_installer.sh
@@ -0,0 +1,28 @@
+#!/bin/sh
+#
+# Setup script to build Windows tool installer with Inno Setup
+#
+# Designed to be run on Linux (with wine) but could be adapted to run under MSYS2 on Windows
+# pretty easily...
+#
+# - Downloads (if necessary) all tools to install to the "dl/" directory
+# - Deletes the "input" directory contains and copies everything under there
+# - Runs ISCC under wine to compile the installer itself
+set -e
+
+cd `dirname $0`
+pushd dl
+wget --continue "https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip"
+wget --continue "https://github.com/espressif/kconfig-frontends/releases/download/v4.6.0.0-idf-20180319/mconf-v4.6.0.0-idf-20180319-win32.zip"
+wget --continue "https://github.com/ninja-build/ninja/releases/download/v1.8.2/ninja-win.zip"
+popd
+
+rm -rf input/*
+pushd input
+unzip ../dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+unzip ../dl/mconf-v4.6.0.0-idf-20180319-win32.zip
+unzip ../dl/ninja-win.zip
+popd
+
+wine "C:\Program Files\Inno Setup 5\ISCC.exe" "`winepath -w ./idf_tool_setup.iss`"
+
diff --git a/tools/windows/tool_setup/idf_tool_setup.iss b/tools/windows/tool_setup/idf_tool_setup.iss
new file mode 100644
index 000000000..8c888e8f0
--- /dev/null
+++ b/tools/windows/tool_setup/idf_tool_setup.iss
@@ -0,0 +1,225 @@
+#include <idp.iss>
+
+[Setup]
+AppName=ESP-IDF Tools
+AppVersion=1.0
+OutputBaseFilename=esp-idf-tools-setup-1.0
+
+DefaultDirName={pf}\Espressif\ESP-IDF Tools
+DefaultGroupName=ESP-IDF Tools
+Compression=lzma2
+SolidCompression=yes
+ChangesEnvironment=yes
+; Note: the rest of the installer setup is written to work cleanly on win32 also, *however*
+; Ninja doesn't ship a 32-bit binary so there's no way yet to install on win32 :(
+; See https://github.com/ninja-build/ninja/issues/1339
+ArchitecturesAllowed=x64
+ArchitecturesInstallIn64BitMode=x64
+
+[Types]
+Name: "full"; Description: "Default installation"
+Name: "custom"; Description: "Custom installation"; Flags: iscustom
+
+[Components]
+Name: toolchain; Description: ESP32 Xtensa GCC Cross-Toolchain; Types: full custom;
+Name: mconf; Description: ESP-IDF console menuconfig tool; Types: full custom;
+Name: ninja; Description: Install Ninja build v1.8.2; Types: full custom
+
+[Tasks]
+; Should installer prepend to Path (does this by default)
+Name: addpath; Description: "Add tools to Path"; GroupDescription: "Add to Path:";
+Name: addpath\allusers; Description: "For all users"; GroupDescription: "Add to Path:"; Flags: exclusive
+Name: addpath\user; Description: "For the current user only"; GroupDescription: "Add to Path:"; Flags: exclusive unchecked
+
+; External installation tasks
+;
+; Note: The Check conditions here auto-select 32-bit or 64-bit installers, as needed
+; The tasks won't appear if CMake/Python27 already appear to be installed on this system
+Name: cmake32; Description: Download and Run CMake 3.11.1 Installer; GroupDescription: "Other Required Tools:"; Check: not IsWin64 and not CMakeInstalled
+Name: cmake64; Description: Download and Run CMake 3.11.1 Installer; GroupDescription: "Other Required Tools:"; Check: IsWin64 and not CMakeInstalled
+Name: python32; Description: Download and Run Python 2.7.14 Installer and install pyserial; GroupDescription: "Other Required Tools:"; Check: not IsWin64 and not Python27Installed
+Name: python64; Description: Download and Run Python 2.7.14 Installer and install pyserial; GroupDescription: "Other Required Tools:"; Check: IsWin64 and not Python27Installed
+
+[Files]
+Components: toolchain; Source: "input\xtensa-esp32-elf\*"; DestDir: "{app}\toolchain\"; Flags: recursesubdirs;
+Components: mconf; Source: "input\mconf-v4.6.0.0-idf-20180319-win32\*"; DestDir: "{app}\mconf\";
+Components: ninja; Source: "input\ninja.exe"; DestDir: "{app}";
+
+[Run]
+Tasks: cmake32 cmake64; Filename: "msiexec.exe"; Parameters: "/i ""{tmp}\cmake.msi"" /qb! {code:GetCMakeInstallerArgs}"; StatusMsg: Running CMake installer...;
+Tasks: python32 python64; Filename: "msiexec.exe"; Parameters: "/i ""{tmp}\python.msi"" /qb! {code:GetPythonInstallerArgs} REBOOT=Supress"; StatusMsg: Running Python installer...;
+Tasks: python32 python64; Filename: "C:\Python27\Scripts\pip.exe"; Parameters: "install pyserial"; StatusMsg: Installing pyserial...;
+
+[Registry]
+; Prepend various entries to Path in the registry. Can either be HKLM (all users) or HKCU (single user only)
+
+; ninja path (in root app directory)
+Root: HKLM; Subkey: "SYSTEM\CurrentControlSet\Control\Session Manager\Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app};{olddata}"; Check: not IsInPath('{app}'); \
+    Components: ninja; Tasks: addpath\allusers
+Root: HKCU; Subkey: "Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app};{olddata}"; Check: not IsInPath('{app}'); \
+    Components: ninja; Tasks: addpath\user
+
+; mconf path
+Root: HKLM; Subkey: "SYSTEM\CurrentControlSet\Control\Session Manager\Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf;{olddata}"; Check: not IsInPath('{app}\mconf'); \
+    Components: mconf; Tasks: addpath\allusers
+Root: HKCU; Subkey: "Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf;{olddata}"; Check: not IsInPath('{app}\mconf'); \
+    Components: mconf; Tasks: addpath\user
+
+; toolchain path
+Root: HKLM; Subkey: "SYSTEM\CurrentControlSet\Control\Session Manager\Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\toolchain\bin;{olddata}"; Check: not IsInPath('{app}\toolchain\bin'); \
+    Components: toolchain; Tasks: addpath\allusers
+Root: HKCU; Subkey: "Environment"; \
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\toolchain\bin;{olddata}"; Check: not IsInPath('{app}\toolchain\bin'); \
+    Components: toolchain; Tasks: addpath\user
+
+
+[Code]
+procedure InitializeWizard;
+begin
+      idpDownloadAfter(wpReady);
+end;
+
+procedure CurPageChanged(CurPageID: Integer);
+begin
+    { When the Ready page is being displayed, initialise downloads based on which Tasks are selected }
+    if CurPageID=wpReady then
+    begin
+      if IsTaskSelected('python32') then
+      begin
+          idpAddFile('https://www.python.org/ftp/python/2.7.14/python-2.7.14.msi',  ExpandConstant('{tmp}\python.msi'));
+      end;
+      if IsTaskSelected('python64') then
+      begin
+          idpAddFile('https://www.python.org/ftp/python/2.7.14/python-2.7.14.amd64.msi', ExpandConstant('{tmp}\python.msi'));
+      end;
+      if IsTaskSelected('cmake32') then
+      begin
+          idpAddFile('https://cmake.org/files/v3.11/cmake-3.11.1-win32-x86.msi', ExpandConstant('{tmp}\cmake.msi'));
+      end;
+      if IsTaskSelected('cmake64') then
+      begin
+          idpAddFile('https://cmake.org/files/v3.11/cmake-3.11.1-win64-x64.msi', ExpandConstant('{tmp}\cmake.msi'));
+      end;
+    end;
+end;
+
+{ Utility to search in HKLM for an installation path. Looks in both 64-bit & 32-bit registry. }
+function GetInstallPath(key, valuename : String) : Variant;
+var
+  value : string;
+begin
+   Result := Null;
+   if RegQueryStringValue(HKEY_LOCAL_MACHINE, key, valuename, value) then
+   begin
+      Result := value;
+   end
+   else
+   begin
+      { This is 32-bit setup running on 64-bit Windows, but ESP-IDF can use 64-bit tools also }
+      if IsWin64 and RegQueryStringValue(HKLM64, key, valuename, value) then
+      begin
+        Result := value;
+      end;
+   end;
+end;
+
+{ Return the path of the CMake install, if there is one }
+function CMakeInstallPath() : Variant;
+begin
+  Result := GetInstallPath('SOFTWARE\Kitware\CMake', 'InstallDir');
+end;
+
+{ Return 'True' if CMake is installed }
+function CMakeInstalled() : Boolean;
+begin
+   Result := not VarIsNull(CMakeInstallPath());
+end;
+
+{ Return the path where Python 2.7 is installed, if there is one }
+function Python27InstallPath() : Variant;
+begin
+  Result := GetInstallPath('SOFTWARE\Python\PythonCore\2.7\InstallPath', '');
+end;
+
+{ Return True if Python 2.7 is installed }
+function Python27Installed() : Boolean;
+begin
+   Result := not VarIsNull(Python27InstallPath());
+end;
+
+{ Return arguments to pass to CMake installer, ie should it add CMake to the Path }
+function GetCMakeInstallerArgs(Param : String) : String;
+begin
+   if IsTaskSelected('addpath\allusers') then
+   begin
+     Result := 'ADD_CMAKE_TO_PATH=System';
+   end
+   else if IsTaskSelected('addpath\user') then
+   begin
+     Result := 'ADD_CMAKE_TO_PATH=User';
+   end
+   else begin
+     Result := 'ADD_CMAKE_TO_PATH=None';
+   end;
+end;
+
+{ Return arguments to pass to the Python installer,
+  ie should it install for all users and should it prepend to the Path }
+function GetPythonInstallerArgs(Param : String) : String;
+begin
+   { Note: The Python 2.7 installer appears to always add PATH to
+     system environment variables, regardless of ALLUSERS setting.
+
+     This appears to be fixed in the Python 3.x installers (which use WiX) }
+   if IsTaskSelected('addpath') then
+   begin
+     Result := 'ADDLOCAL=ALL ';
+   end
+   else begin
+     Result := ''
+   end;
+   if IsTaskSelected('addpath\allusers') then
+   begin
+     Result := Result + 'ALLUSERS=1';
+   end
+   else begin
+     Result := Result + 'ALLUSERS=';
+   end;
+end;
+
+
+{ Return True if the param is already set in the Path
+  (user or system, depending on which Task is chosen)
+
+  Adapted from https://stackoverflow.com/a/3431379
+}
+function IsInPath(Param: string): boolean;
+var
+  OrigPath: string;
+  RootKey : Integer;
+  SubKey : String;
+begin
+  if IsTaskSelected('addpath\allusers') then
+  begin
+    RootKey := HKEY_LOCAL_MACHINE;
+    SubKey := 'SYSTEM\CurrentControlSet\Control\Session Manager\Environment';
+  end
+  else begin
+    RootKey := HKEY_CURRENT_USER;
+    SubKey := 'Environment';
+  end;
+
+  if not RegQueryStringValue(RootKey, SubKey, 'Path', OrigPath)
+  then begin
+    Result := False;
+  end
+  else begin
+    { look for the path with leading and trailing semicolon }
+    Result := Pos(';' + Param + ';', ';' + OrigPath + ';') > 0;
+  end;
+end;

From d5a58971402a5bebe126a809544304b2f385f36d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 27 Apr 2018 11:17:23 +1000
Subject: [PATCH 048/112] docs: Temporarily allow cmake docs to be in English
 only

---
 docs/check_lang_folder_sync.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/check_lang_folder_sync.sh b/docs/check_lang_folder_sync.sh
index 96de9994c..5840bea2a 100755
--- a/docs/check_lang_folder_sync.sh
+++ b/docs/check_lang_folder_sync.sh
@@ -20,7 +20,8 @@ find zh_CN -type f | cut -d/ -f2- | sort > file_list_zh_CN
 # format is to display new or different filenames
 DIFF_FORMAT="--unchanged-line-format= --old-line-format=[en]:%L --new-line-format=[zh_CN]:%L"
 
-FOLDER_DIFFERENCES=$(diff $DIFF_FORMAT file_list_en file_list_zh_CN)
+# TEMPORARY MODIFICATION: -cmake docs are English-only for now
+FOLDER_DIFFERENCES=$(diff $DIFF_FORMAT file_list_en file_list_zh_CN | grep -v "cmake")
 if ! [ -z "$FOLDER_DIFFERENCES" ]; then
     echo "$STARS"
     echo "Build failed due to the following differences in 'en' and 'zh_CN' folders:"

From 918c4b4c48cd3578ec5cbd2f20f8d0255818fa5d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 27 Apr 2018 17:10:51 +1000
Subject: [PATCH 049/112] Temporarily add feature/cmake to the list of branches
 we auto-push to github

---
 .gitlab-ci.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index be3bb0ba0..71ae62672 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -407,10 +407,11 @@ push_master_to_github:
     - master
     - /^release\/v/
     - /^v\d+\.\d+(\.\d+)?($|-)/
+    - feature/cmake
   when: on_success
   dependencies: []
   variables:
-    GITHUB_PUSH_REFS: refs/remotes/origin/release refs/remotes/origin/master
+    GITHUB_PUSH_REFS: refs/remotes/origin/release refs/remotes/origin/master refs/remotes/origin/feature/cmake
   before_script: *do_nothing_before
   script:
     - mkdir -p ~/.ssh

From f6db61e4f472b3a5d792312616d8b5678de6f4c2 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 30 Apr 2018 15:44:05 +1000
Subject: [PATCH 050/112] cmake docs: Fix Windows tools installer download URL

---
 docs/en/get-started/windows-setup-cmake.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/get-started/windows-setup-cmake.rst b/docs/en/get-started/windows-setup-cmake.rst
index 8c4ac6db3..0545e7d50 100644
--- a/docs/en/get-started/windows-setup-cmake.rst
+++ b/docs/en/get-started/windows-setup-cmake.rst
@@ -18,7 +18,7 @@ ESP-IDF Tools Installer
 
 The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
 
-https://dl.espressif.com/esp-idf-tools-setup-1.0.exe
+https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe
 
 The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and mconf configuration tool. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
 

From c42b791aaa85797e7496ccd71daad18e5877bf80 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 15:42:28 +1000
Subject: [PATCH 051/112] cmake: Use prebuilt mconf on Windows

Closes https://github.com/espressif/esp-idf/issues/1905
---
 tools/cmake/kconfig.cmake | 48 ++++++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 16 deletions(-)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index e313c886a..bda5c87bc 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -1,8 +1,6 @@
 include(ExternalProject)
 
 macro(kconfig_set_variables)
-    set(MCONF kconfig_bin/mconf)
-
     set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
     set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
     set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
@@ -13,19 +11,37 @@ macro(kconfig_set_variables)
     set_default(SDKCONFIG_DEFAULTS "${SDKCONFIG}.defaults")
 endmacro()
 
-# Use the existing Makefile to build mconf (out of tree) when needed
-#
-# TODO: Download(?) a prebuilt mingw mconf on Windows
-externalproject_add(mconf
-    SOURCE_DIR ${IDF_PATH}/tools/kconfig
-    CONFIGURE_COMMAND ""
-    BINARY_DIR "kconfig_bin"
-    BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
-    BUILD_BYPRODUCTS ${MCONF}
-    INSTALL_COMMAND ""
-    EXCLUDE_FROM_ALL 1
-    )
+if(CMAKE_HOST_WIN32)
+    # Prefer a prebuilt mconf on Windows
+    find_program(MCONF mconf)
 
+    if(NOT MCONF)
+        find_program(NATIVE_GCC gcc)
+        if(NOT NATIVE_GCC)
+            message(FATAL_ERROR
+                "Windows requires a prebuilt ESP-IDF-specific mconf for your platform "
+                "on the PATH, or an MSYS2 version of gcc on the PATH to build mconf. "
+                "Consult the setup docs for ESP-IDF on Windows.")
+        endif()
+    endif()
+endif()
+
+if(NOT MCONF)
+    # Use the existing Makefile to build mconf (out of tree) when needed
+    #
+    set(MCONF kconfig_bin/mconf)
+
+    externalproject_add(mconf
+        SOURCE_DIR ${IDF_PATH}/tools/kconfig
+        CONFIGURE_COMMAND ""
+        BINARY_DIR "kconfig_bin"
+        BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
+        BUILD_BYPRODUCTS ${MCONF}
+        INSTALL_COMMAND ""
+        EXCLUDE_FROM_ALL 1
+        )
+    set(menuconfig_depends DEPENDS mconf)
+endif()
 
 # Find all Kconfig files for all components
 function(kconfig_process_config)
@@ -66,9 +82,9 @@ function(kconfig_process_config)
         --env "COMPONENT_KCONFIGS=${kconfigs}"
         --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}")
 
-    # Generate the menuconfig target (uses C-based mconf tool)
+    # Generate the menuconfig target (uses C-based mconf tool, either prebuilt or via mconf target above)
     add_custom_target(menuconfig
-        DEPENDS mconf
+        ${menuconfig_depends}
         # create any missing config file, with defaults if necessary
         COMMAND ${confgen_basecommand} --output config ${SDKCONFIG}
         COMMAND ${CMAKE_COMMAND} -E env

From c7307de63ece94f7cbf147d7fc1a7d45b4a5f55f Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 16:05:27 +1000
Subject: [PATCH 052/112] cmake: Automatically pull in winpty for menuconfig,
 monitor if needed

---
 tools/cmake/kconfig.cmake | 3 +++
 tools/idf.py              | 2 ++
 2 files changed, 5 insertions(+)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index bda5c87bc..eeb8ce113 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -13,6 +13,7 @@ endmacro()
 
 if(CMAKE_HOST_WIN32)
     # Prefer a prebuilt mconf on Windows
+    find_program(WINPTY winpty)
     find_program(MCONF mconf)
 
     if(NOT MCONF)
@@ -23,6 +24,8 @@ if(CMAKE_HOST_WIN32)
                 "on the PATH, or an MSYS2 version of gcc on the PATH to build mconf. "
                 "Consult the setup docs for ESP-IDF on Windows.")
         endif()
+    elseif(WINPTY)
+        set(MCONF "${WINPTY}" "${MCONF}")
     endif()
 endif()
 
diff --git a/tools/idf.py b/tools/idf.py
index 9064a8178..247fd3b9f 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -267,6 +267,8 @@ def monitor(action, args):
         monitor_args += [ "-p", args.port ]
     monitor_args += [ "-b", project_desc["monitor_baud"] ]
     monitor_args += [ elf_file ]
+    if "MSYSTEM" is os.environ:
+        monitor_args = [ "winpty" ] + monitor_args
     _run_tool("idf_monitor", monitor_args, args.build_dir)
 
 

From 2fadf8a0004c2e1f4b5d46f3346ade0c778aeb44 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 16:42:35 +1000
Subject: [PATCH 053/112] cmake docs: Fix variable expansion when adding tools
 dir to PATH

---
 docs/en/get-started/add-idf_path-to-profile-cmake.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
index 0f5cbcef1..1ec8a7975 100644
--- a/docs/en/get-started/add-idf_path-to-profile-cmake.rst
+++ b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
@@ -39,7 +39,7 @@ Linux and MacOS
 Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file::
 
     export IDF_PATH=~/esp/esp-idf
-    export PATH="$PATH:'$IDF_PATH/tools'"
+    export PATH="$PATH:$IDF_PATH/tools"
 
 Log off and log in back to make this change effective.
 

From 68282cf80b0803e924ecb3902d22d8c58bf68af5 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 16:54:27 +1000
Subject: [PATCH 054/112] heap/cmake: Fix linking error when heap tracing is
 enabled

---
 components/heap/CMakeLists.txt | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/components/heap/CMakeLists.txt b/components/heap/CMakeLists.txt
index b7dd5d9ac..9c4ccf16d 100644
--- a/components/heap/CMakeLists.txt
+++ b/components/heap/CMakeLists.txt
@@ -12,7 +12,15 @@ register_component()
 
 if(CONFIG_HEAP_TRACING)
     set(WRAP_FUNCTIONS
-        calloc malloc free realloc heap_caps_malloc heap_caps_free heap_caps_realloc)
+        calloc
+        malloc
+        free
+        realloc
+        heap_caps_malloc
+        heap_caps_free
+        heap_caps_realloc
+        heap_caps_malloc_default
+        heap_caps_realloc_default)
 
     foreach(wrap ${WRAP_FUNCTIONS})
         target_link_libraries(heap "-Wl,--wrap=${wrap}")

From 9ec14decce30749c1aa6e76d2dee24d672bea69f Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 17:01:36 +1000
Subject: [PATCH 055/112] cmake: Fix idf_size.py merge errors

---
 tools/idf_size.py | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/tools/idf_size.py b/tools/idf_size.py
index d67cfa25a..d207906b2 100755
--- a/tools/idf_size.py
+++ b/tools/idf_size.py
@@ -102,12 +102,13 @@ def load_sections(map_file):
         # source file line, ie
         # 0x0000000040080400       0xa4 /home/gus/esp/32/idf/examples/get-started/hello_world/build/esp32/libesp32.a(cpu_start.o)
         RE_SOURCE_LINE = r"\s*(?P<sym_name>\S*).* +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<archive>.+\.a)\((?P<object_file>.+\.ob?j?)\)"
-        m = re.match(RE_SOURCE_LINE, line)
+
+        m = re.match(RE_SOURCE_LINE, line, re.M)
         if not m:
             # cmake build system links some object files directly, not part of any archive
-            RE_SOURCE_LINE = r".*? +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<object_file>.+\.ob?j?)"
+            RE_SOURCE_LINE = r"\s*(?P<sym_name>\S*).* +0x(?P<address>[\da-f]+) +0x(?P<size>[\da-f]+) (?P<object_file>.+\.ob?j?)"
             m = re.match(RE_SOURCE_LINE, line)
-        if section is not None and m is not None:  # input source file details
+        if section is not None and m is not None:  # input source file details=ma,e
             sym_name = m.group("sym_name") if len(m.group("sym_name")) > 0 else sym_backup
             try:
                 archive = m.group("archive")
@@ -117,7 +118,7 @@ def load_sections(map_file):
             source = {
                 "size" : int(m.group("size"), 16),
                 "address" : int(m.group("address"), 16),
-                "archive" : os.path.basename(archive)),
+                "archive" : os.path.basename(archive),
                 "object_file" : os.path.basename(m.group("object_file")),
                 "sym_name" : sym_name,
             }

From 48c3ad37f1ce3ea4800c296684ab75a8423dfdf4 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 1 May 2018 17:07:21 +1000
Subject: [PATCH 056/112] docs/cmake: Add some notes about need to set IDF_PATH
 and/or PATH in certain configurations

---
 docs/en/get-started/add-idf_path-to-profile-cmake.rst | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
index 1ec8a7975..b1f1247d1 100644
--- a/docs/en/get-started/add-idf_path-to-profile-cmake.rst
+++ b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
@@ -11,8 +11,11 @@ To use the CMake-based build system and the idf.py tool, two modifications need
 
 To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
 
-.. note::
-   If you only plan to use ``idf.py`` from the command line, and don't need integration with any IDEs, then you can skip setting ``IDF_PATH``. ``idf.py`` will use its own IDF directory as the default ``IDF_PATH``.
+.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
+
+.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
+
+.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
 
 .. _add-paths-to-profile-windows-cmake:
 
@@ -59,8 +62,9 @@ To verify idf.py is now on the ``PATH``, you can run the following::
 
 A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
 
-If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
+If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
 
     export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:$IDF_PATH/tools"
 
 If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.

From 8453806a8c74e0398f536d3ea14a463f896c722f Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 4 May 2018 14:06:15 +1000
Subject: [PATCH 057/112] idf.py: Fix 'idf.py monitor' build & flash targets

---
 tools/idf.py         | 27 +++++++++++++++++++++------
 tools/idf_monitor.py | 34 ++++++++++++++++++++--------------
 2 files changed, 41 insertions(+), 20 deletions(-)

diff --git a/tools/idf.py b/tools/idf.py
index 247fd3b9f..989f31063 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -267,9 +267,13 @@ def monitor(action, args):
         monitor_args += [ "-p", args.port ]
     monitor_args += [ "-b", project_desc["monitor_baud"] ]
     monitor_args += [ elf_file ]
+
+    idf_py = [ PYTHON ] + get_commandline_options()  # commands to re-run idf.py
+    monitor_args += [ "-m", " ".join("'%s'" % a for a in idf_py) ]
+
     if "MSYSTEM" is os.environ:
         monitor_args = [ "winpty" ] + monitor_args
-    _run_tool("idf_monitor", monitor_args, args.build_dir)
+    _run_tool("idf_monitor", monitor_args, args.project_dir)
 
 
 def clean(action, args):
@@ -311,16 +315,16 @@ ACTIONS = {
     "build":                 ( "all",        [], [] ),  # build is same as 'all' target
     "clean":                 ( clean,        [], [ "fullclean" ] ),
     "fullclean":             ( fullclean,    [], [] ),
-    "reconfigure":           ( reconfigure,  [], [] ),
+    "reconfigure":           ( reconfigure,  [], [ "menuconfig" ] ),
     "menuconfig":            ( build_target, [], [] ),
-    "size":                  ( build_target, [], [ "app" ] ),
-    "size-components":       ( build_target, [], [ "app" ] ),
-    "size-files":            ( build_target, [], [ "app" ] ),
+    "size":                  ( build_target, [ "app" ], [] ),
+    "size-components":       ( build_target, [ "app" ], [] ),
+    "size-files":            ( build_target, [ "app" ], [] ),
     "bootloader":            ( build_target, [], [] ),
     "bootloader-clean":      ( build_target, [], [] ),
     "bootloader-flash":      ( flash,        [ "bootloader" ], [] ),
     "app":                   ( build_target, [], [ "clean", "fullclean", "reconfigure" ] ),
-    "app-flash":             ( flash,        [], [ "app" ]),
+    "app-flash":             ( flash,        [ "app" ], []),
     "partition_table":       ( build_target, [], [ "reconfigure" ] ),
     "partition_table-flash": ( flash,        [ "partition_table" ], []),
     "flash":                 ( flash,        [ "all" ], [ ] ),
@@ -329,6 +333,17 @@ ACTIONS = {
 }
 
 
+def get_commandline_options():
+    """ Return all the command line options up to but not including the action """
+    result = []
+    for a in sys.argv:
+        if a in ACTIONS.keys():
+            break
+        else:
+            result.append(a)
+    return result
+
+
 def main():
     parser = argparse.ArgumentParser(description='ESP-IDF build management tool')
     parser.add_argument('-p', '--port', help="Serial port", default=None)
diff --git a/tools/idf_monitor.py b/tools/idf_monitor.py
index 75d7a63e9..29347efc9 100755
--- a/tools/idf_monitor.py
+++ b/tools/idf_monitor.py
@@ -3,8 +3,8 @@
 # esp-idf serial output monitor tool. Does some helpful things:
 # - Looks up hex addresses in ELF file with addr2line
 # - Reset ESP32 via serial RTS line (Ctrl-T Ctrl-R)
-# - Run "make flash" (Ctrl-T Ctrl-F)
-# - Run "make app-flash" (Ctrl-T Ctrl-A)
+# - Run "make/idf.py flash" (Ctrl-T Ctrl-F)
+# - Run "make/idf.py app-flash" (Ctrl-T Ctrl-A)
 # - If gdbstub output is detected, gdb is automatically loaded
 #
 # Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
@@ -37,6 +37,7 @@ try:
     import queue
 except ImportError:
     import Queue as queue
+import shlex
 import time
 import sys
 import serial
@@ -243,7 +244,10 @@ class Monitor(object):
         self.console_reader = ConsoleReader(self.console, self.event_queue)
         self.serial_reader = SerialReader(self.serial, self.event_queue)
         self.elf_file = elf_file
-        self.make = make
+        if not os.path.exists(make):
+            self.make = shlex.split(make)  # allow for possibility the "make" arg is a list of arguments (for idf.py)
+        else:
+            self.make = make
         self.toolchain_prefix = toolchain_prefix
         self.menu_key = CTRL_T
         self.exit_key = CTRL_RBRACKET
@@ -355,19 +359,18 @@ class Monitor(object):
 ---    {menu:7} Send the menu character itself to remote
 ---    {exit:7} Send the exit character itself to remote
 ---    {reset:7} Reset target board via RTS line
----    {make:7} Run 'make flash' to build & flash
----    {appmake:7} Run 'make app-flash to build & flash app
+---    {makecmd:7} Build & flash project
+---    {appmake:7} Build & flash app only
 ---    {output:7} Toggle output display
 ---    {pause:7} Reset target into bootloader to pause app via RTS line
 """.format(version=__version__,
            exit=key_description(self.exit_key),
            menu=key_description(self.menu_key),
            reset=key_description(CTRL_R),
-           make=key_description(CTRL_F),
+           makecmd=key_description(CTRL_F),
            appmake=key_description(CTRL_A),
            output=key_description(CTRL_Y),
-           pause=key_description(CTRL_P),
-           )
+           pause=key_description(CTRL_P) )
 
     def __enter__(self):
         """ Use 'with self' to temporarily disable monitoring behaviour """
@@ -385,12 +388,12 @@ class Monitor(object):
             red_print("""
 --- {}
 --- Press {} to exit monitor.
---- Press {} to run 'make flash'.
---- Press {} to run 'make app-flash'.
+--- Press {} to build & flash project.
+--- Press {} to build & flash app.
 --- Press any other key to resume monitor (resets target).""".format(reason,
                                                                      key_description(self.exit_key),
                                                                      key_description(CTRL_F),
-                                                                     key_description(CTRL_A)))
+                                                                     key_description(CTRL_A) ))
             k = CTRL_T  # ignore CTRL-T here, so people can muscle-memory Ctrl-T Ctrl-F, etc.
             while k == CTRL_T:
                 k = self.console.getkey()
@@ -404,9 +407,12 @@ class Monitor(object):
 
     def run_make(self, target):
         with self:
-            yellow_print("Running make %s..." % target)
-            p = subprocess.Popen([self.make,
-                                  target ])
+            if isinstance(self.make, list):
+                popen_args = self.make + [ target ]
+            else:
+                popen_args = [ self.make, target ]
+            yellow_print("Running %s..." % " ".join(popen_args))
+            p = subprocess.Popen(popen_args)
             try:
                 p.wait()
             except KeyboardInterrupt:

From c7f19e76d7bcb62762ba36ea000c3f9f958f3dc7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 3 May 2018 14:22:35 +1000
Subject: [PATCH 058/112] docs: Move main docs to cover CMake

Add "GNU Make build system" doc with "cheat sheet" for moving to new system
---
 README.md                                     |  40 +-
 components/ethernet/emac_main.c               |   2 +-
 components/spi_flash/README.rst               |   2 +-
 docs/en/api-guides/build-system-cmake.rst     | 799 ----------------
 docs/en/api-guides/build-system.rst           | 899 +++++++++++-------
 docs/en/api-guides/cmake-preview-index.rst    |  10 -
 docs/en/api-guides/console.rst                |   2 +-
 docs/en/api-guides/core_dump.rst              |   4 +-
 docs/en/api-guides/gnu-make-build-system.rst  |  51 +
 .../jtag-debugging/setup-openocd-windows.rst  |   4 +-
 .../add-idf_path-to-profile-cmake.rst         |  70 --
 .../get-started/add-idf_path-to-profile.rst   |  62 +-
 docs/en/get-started/eclipse-setup-windows.rst |  78 --
 docs/en/get-started/eclipse-setup.rst         | 104 +-
 .../establish-serial-connection.rst           |   3 -
 docs/en/get-started/idf-monitor.rst           |   9 +-
 docs/en/get-started/index-cmake.rst           | 347 -------
 docs/en/get-started/index.rst                 | 180 +++-
 docs/en/get-started/linux-setup-cmake.rst     | 113 ---
 docs/en/get-started/linux-setup-scratch.rst   |  21 +-
 docs/en/get-started/linux-setup.rst           |  12 +-
 docs/en/get-started/macos-setup-cmake.rst     |  64 --
 docs/en/get-started/macos-setup-scratch.rst   |  28 +-
 docs/en/get-started/macos-setup.rst           |  23 +-
 docs/en/get-started/windows-setup-cmake.rst   |  58 --
 .../windows-setup-scratch-cmake.rst           |  85 --
 docs/en/get-started/windows-setup-scratch.rst | 167 ++--
 docs/en/get-started/windows-setup.rst         |  67 +-
 docs/en/index.rst                             |   4 +-
 .../api-guides/gnu-make-build-system.rst      |   1 +
 .../get-started/eclipse-setup-windows.rst     |  81 --
 docs/zh_CN/get-started/eclipse-setup.rst      | 103 +-
 docs/zh_CN/get-started/index.rst              |   2 +
 docs/zh_CN/get-started/linux-setup.rst        |   2 +
 docs/zh_CN/get-started/macos-setup.rst        |   2 +
 docs/zh_CN/get-started/windows-setup.rst      |   4 +-
 tools/idf.py                                  |   8 +-
 tools/unit-test-app/README.md                 |   2 +-
 38 files changed, 996 insertions(+), 2517 deletions(-)
 delete mode 100644 docs/en/api-guides/build-system-cmake.rst
 delete mode 100644 docs/en/api-guides/cmake-preview-index.rst
 create mode 100644 docs/en/api-guides/gnu-make-build-system.rst
 delete mode 100644 docs/en/get-started/add-idf_path-to-profile-cmake.rst
 delete mode 100644 docs/en/get-started/eclipse-setup-windows.rst
 delete mode 100644 docs/en/get-started/index-cmake.rst
 delete mode 100644 docs/en/get-started/linux-setup-cmake.rst
 delete mode 100644 docs/en/get-started/macos-setup-cmake.rst
 delete mode 100644 docs/en/get-started/windows-setup-cmake.rst
 delete mode 100644 docs/en/get-started/windows-setup-scratch-cmake.rst
 create mode 100644 docs/zh_CN/api-guides/gnu-make-build-system.rst
 delete mode 100644 docs/zh_CN/get-started/eclipse-setup-windows.rst

diff --git a/README.md b/README.md
index df29f2221..631d54a40 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Once you've found the project you want to work with, change to its directory and
 
 ## Configuring the Project
 
-`make menuconfig`
+`idf.py menuconfig`
 
 * Opens a text-based configuration menu for the project.
 * Use up & down arrow keys to navigate the menu.
@@ -36,51 +36,41 @@ Once done configuring, press Escape multiple times to exit and say "Yes" to save
 
 ## Compiling the Project
 
-`make all`
+`idf.py build`
 
 ... will compile app, bootloader and generate a partition table based on the config.
 
 ## Flashing the Project
 
-When `make all` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running:
+When the build finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this automatically by running:
 
-`make flash`
+`idf.py flash`
 
-This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `make menuconfig`.
+This will flash the entire project (app, bootloader and partition table) to a new chip. The settings for serial port flashing can be configured with `idf.py menuconfig`.
 
-You don't need to run `make all` before running `make flash`, `make flash` will automatically rebuild anything which needs it.
+You don't need to run `idf.py build` before running `idf.py flash`, `idf.py flash` will automatically rebuild anything which needs it.
 
 ## Viewing Serial Output
 
-The `make monitor` target uses the [idf_monitor tool](https://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html).
+The `idf.py monitor` target uses the [idf_monitor tool](https://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html) to display serial output from the ESP32. idf_monitor also has a range of features to decode crash output and interact with the device. [Check the documentation page for details](https://esp-idf.readthedocs.io/en/latest/get-started/idf-monitor.html).
 
 Exit the monitor by typing Ctrl-].
 
 To flash and monitor output in one pass, you can run:
 
-`make flash monitor`
+`idf.py flash monitor`
 
 ## Compiling & Flashing Just the App
 
 After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
 
-* `make app` - build just the app.
-* `make app-flash` - flash just the app.
+* `idf.py app` - build just the app.
+* `idf.py app-flash` - flash just the app.
 
-`make app-flash` will automatically rebuild the app if it needs it.
+`idf.py app-flash` will automatically rebuild the app if it needs it.
 
 (In normal development there's no downside to reflashing the bootloader and partition table each time, if they haven't changed.)
 
-## Parallel Builds
-
-ESP-IDF supports compiling multiple files in parallel, so all of the above commands can be run as `make -jN` where `N` is the number of parallel make processes to run (generally N should be equal to or one more than the number of CPU cores in your system.)
-
-Multiple make functions can be combined into one. For example: to build the app & bootloader using 5 jobs in parallel, then flash everything, and then display serial output from the ESP32 run:
-
-```
-make -j5 flash monitor
-```
-
 ## The Partition Table
 
 Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
@@ -89,20 +79,20 @@ A single ESP32's flash can contain multiple apps, as well as many different kind
 
 Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
 
-The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
+The simplest way to use the partition table is to `idf.py menuconfig` and choose one of the simple predefined partition tables:
 
 * "Single factory app, no OTA"
 * "Factory app, two OTA definitions"
 
-In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
+In both cases the factory app is flashed at offset 0x10000. If you `idf.py partition_table` then it will print a summary of the partition table.
 
 For more details about partition tables and how to create custom variations, view the [`docs/en/api-guides/partition-tables.rst`](docs/en/api-guides/partition-tables.rst) file.
 
 ## Erasing Flash
 
-The `make flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `make erase_flash`.
+The `idf.py flash` target does not erase the entire flash contents. However it is sometimes useful to set the device back to a totally erased state, particularly when making partition table changes or OTA app updates. To erase the entire flash, run `idf.py erase_flash`.
 
-This can be combined with other targets, ie `make erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
+This can be combined with other targets, ie `idf.py erase_flash flash` will erase everything and then re-flash the new app, bootloader and partition table.
 
 # Resources
 
diff --git a/components/ethernet/emac_main.c b/components/ethernet/emac_main.c
index b8c94b0fa..5605ea860 100644
--- a/components/ethernet/emac_main.c
+++ b/components/ethernet/emac_main.c
@@ -275,7 +275,7 @@ static void emac_set_user_config_data(eth_config_t *config )
     emac_config.emac_flow_ctrl_enable = config->flow_ctrl_enable;
 #else
     if(config->flow_ctrl_enable == true) {
-        ESP_LOGE(TAG, "eth flow ctrl init err!!! Please run make menuconfig and make sure DMA_RX_BUF_NUM > 9 .");
+        ESP_LOGE(TAG, "eth flow ctrl init err!!! Please run idf.py menuconfig and make sure DMA_RX_BUF_NUM > 9 .");
     }
     emac_config.emac_flow_ctrl_enable = false;
 #endif
diff --git a/components/spi_flash/README.rst b/components/spi_flash/README.rst
index ef4cb1f82..601603954 100644
--- a/components/spi_flash/README.rst
+++ b/components/spi_flash/README.rst
@@ -36,7 +36,7 @@ image header, flashed at offset 0x1000.
 By default, the SPI flash size is detected by esptool.py when this bootloader is
 written to flash, and the header is updated with the correct
 size. Alternatively, it is possible to generate a fixed flash size by setting
-:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``make menuconfig``.
+:ref:`CONFIG_ESPTOOLPY_FLASHSIZE` in ``idf.py menuconfig``.
 
 If it is necessary to override the configured flash size at runtime, is is
 possible to set the ``chip_size`` member of ``g_rom_flashchip`` structure. This
diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
deleted file mode 100644
index 717589634..000000000
--- a/docs/en/api-guides/build-system-cmake.rst
+++ /dev/null
@@ -1,799 +0,0 @@
-CMake-based Build System
-************************
-
-This document explains the CMake-based ESP-IDF build system and the concept of "components".
-
-Read this document if you want to know how to organise and build a new ESP-IDF project using the CMake-based build system.
-
-We recommend using the esp-idf-template_ project as a starting point for your project.
-
-Preview Release
-===============
-
-.. note::
-    The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The document describing the :doc:`fully supported non-CMake build system is here </api-guides/build-system>`.
-
-CMake-based build system preview release temporarily has the following limitations:
-
-- No instructions published for use with any IDEs.
-- No support for building ULP firmware as part of the build.
-- No support for flash encryption, secure boot.
-- ``idf.py monitor`` only runs at 115200bps
-- The rebuild/reflash commands inside monitor don't work correctly.
-
-These missing features will be added before CMake support is officially supported.
-
-Overview
-========
-
-An ESP-IDF project can be seen as an amalgamation of a number of components.
-For example, for a webserver that shows the current humidity, there could be:
-
-- The ESP32 base libraries (libc, ROM bindings, etc)
-- The WiFi drivers
-- A TCP/IP stack
-- The FreeRTOS operating system
-- A webserver
-- A driver for the humidity sensor
-- Main code tying it all together
-
-ESP-IDF makes these components explicit and configurable. To do that,
-when a project is compiled, the build system will look up all the
-components in the ESP-IDF directories, the project directories and
-(optionally) in additional custom component directories. It then
-allows the user to configure the ESP-IDF project using a a text-based
-menu system to customize each component. After the components in the
-project are configured, the build system will compile the project.
-
-Concepts
---------
-
-- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader.
-
-- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
-
-- An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
-
-- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
-
-Some things are not part of the project:
-
-- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
-
-- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
-
-Using the Build System
-======================
-
-idf.py
-------
-
-The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
-
-- CMake_, which configures the project to be built
-- A command line build tool (either Ninja_ build or `GNU Make`)
-- `esptool.py`_ for flashing ESP32.
-
-The :ref:`getting started guide <get-started-configure-cmake>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
-
-``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
-
-Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
-
-- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
-- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
-  - Create the build directory if needed. The subdirectory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
-  - Run CMake_ as necessary to configure the project and generate build files for the main build tool.
-  - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
-  Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
-- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
-- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care.
-- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
-- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
-- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor.
-
-Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean build flash monitor`` will perform a clean build of the project, then flash to the ESP32 and run the serial monitor.
-
-Advanced Commands
-^^^^^^^^^^^^^^^^^
-
-- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
-- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
-- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
-- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
-
-Using CMake Directly
---------------------
-
-``idf.py`` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
-
-When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands::
-
-  mkdir -p build
-  cd build
-  cmake .. -G Ninja   # or 'GNU Make'
-  ninja
-
-In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: runnning ``ninja`` actually builds the project.
-
-It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguring.
-
-If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - for example running ``make menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
-
-.. note::
-   If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
-
-Using CMake in an IDE
----------------------
-
-You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
-
-When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
-
-Example Project
-===============
-
-An example project directory tree might look like this::
-
-    - myProject/
-                 - CMakeLists.txt
-                 - sdkconfig
-                 - components/ - component1/ - CMakeLists.txt
-                                             - Kconfig
-                                             - src1.c
-                               - component2/ - CMakeLists.txt
-                                             - Kconfig
-                                             - src1.c
-                                             - include/ - component2.h
-                 - main/       - src1.c
-                               - src2.c
-
-                 - build/
-
-This example "myProject" contains the following elements:
-
-- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
-  implements the rest of the build system. Finally, it sets the project name and defines the project.
-
-- "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
-
-- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
-
-- "main" directory is a special "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
-
-- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
-
-Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
-to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
-
-Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
-
-Project CMakeLists File
-=======================
-
-Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
-
-Minimal Example CMakeLists
---------------------------
-
-::
-      cmake_minimum_required(VERSION 3.5)
-
-      set(MAIN_SRCS main/src1.c main/src2.c)
-
-      include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-      project(myProject)
-
-
-Mandatory Parts
----------------
-
-The inclusion of these four lines, in the order shown above, is necessary for every project:
-
-- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
-- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged.
-
-  It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
-
-   ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
-- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
-- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
-
-
-Optional Project Variables
---------------------------
-
-These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
-
-- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
-- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
-- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list doesn't need to include dependencies in this way.
-- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically treated to be in every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this is set to the minimal set of core "system" components needed for any ESP-IDF project.
-
-Any paths in these variables can be absolute paths, or set relative to the project directory.
-
-To set these variables, use the `cmake set command <cmake-set>` ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
-
-
-Component CMakeLists Files
-==========================
-
-Each project contains one or more components. Components can be part of esp-idf, part of the project's own components directory, or added from custom component directories (see above).
-
-A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
-
-Searching for Components
-------------------------
-
-The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose subdirectories are components.
-
-When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
-
-Multiple components with the same name
---------------------------------------
-
-When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
-contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components
-with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
-If used in this way, the ESP-IDF directory itself can remain untouched.
-
-Minimal Component CMakeLists
-----------------------------
-
-The minimal component ``CMakeLists.txt`` file is as follows::
-
-  set(COMPONENT_SRCDIRS ".")
-  set(COMPONENT_ADD_INCLUDEDIRS "include")
-  register_component()
-
-- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
-- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for all other components, and the main source files.
-- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if() statement<cmake-if>` or similar), this component will not be built at all.
-
-Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
-
-See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
-
-.. _component variables:
-
-Preset Component Variables
---------------------------
-
-The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
-
-- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
-- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
-
-The following variables are set at the project level, but available for use in component CMakeLists:
-
-- ``PROJECT_NAME``: Name of the project, as set in project Makefile
-- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
-- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
-- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. `More information here </api-reference/kconfig>`.
-- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
-
-If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
-
-
-- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
-  directory, which will be added to the include search path for
-  all other components which require this one. If an include directory is only needed to compile
-  this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
-- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If a public header header file listed in ``COMPONENT_ADD_INCLUDEDIRS`` includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
-
-  The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
-
-  If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
-
-  See `Component Requirements` for more details.
-
-Optional Component-Specific Variables
--------------------------------------
-
-The following variables can be set inside ``component.mk`` to control the build of that component:
-
-- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
-  the component directory, which will be added to the include search
-  path for this component's source files only.
-- ``COMPONENT_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details.
-- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
-  component directory, which will be searched for source files (``*.cpp``,
-  ``*.c``, ``*.S``). Set this to specify a list of directories
-  which contain source files.
-- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
-  If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add paths to include search paths.
-
-Controlling Component Compilation
----------------------------------
-
-To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
-
-  component_compile_options(-Wno-unused-variable)
-
-This is a wrapper around the CMake `target_compile_options`_ command.
-
-To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
-
-    set_source_files_properties(mysrc.c
-        PROPERTIES COMPILE_FLAGS
-        -Wno-unused-variable
-    )
-
-This can be useful if there is upstream code that emits warnings.
-
-When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
-
-Component Configuration
-=======================
-
-Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
-configuration settings to add to the "make menuconfig" for this component.
-
-These settings are found under the "Component Settings" menu when menuconfig is run.
-
-To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with esp-idf.
-
-For an example, see `Adding conditional configuration`_.
-
-Preprocessor Definitions
-========================
-
-The ESP-IDF build system adds the following C preprocessor definitions on the command line:
-
-- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
-- ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
-
-Component Requirements
-======================
-
-When compiling each component, the ESP-IDF build system recurisvely evaluates its components.
-
-Each component's source file is compiled with these include path directories:
-
-- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
-- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
-- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
-
-When writing a component
-------------------------
-
-- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
-- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
-- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
-- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
-- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
-
-When creating a project
------------------------
-
-- By default, every component is included in the build.
-- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
-  - Components mentioned explicitly in ``COMPONENTS``.
-  - Those components' requirements (evaluated recursively).
-  - The "common" components that every component depends on.
-- Setting ``COMPONENTS`` to the minimal list of components you need can significantly reduce your project's compile time.
-- When compiling the project's source files (``MAIN_SRCS``), the public header directories of all components included in the build are available.
-
-Requirements in the build system implementation
-------------------------------------------------------------------
-
-- Very early in the cmake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
-- The main cmake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
-- Configuration is then evaluated for the components included in the build.
-- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
-
-Build Process Internals
-=======================
-
-For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`.
-
-project.cmake contents
-----------------------
-
-When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environmenmt.
-
-It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality.
-
-project function
-----------------
-
-The custom ``project()`` function performs the following steps:
-
-- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see `above<requirements-in-the-build-system-implementation>`).
-- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
-- Loads the project configuration from the ``sdkconfig`` file and produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
-- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
-- Declare the actual cmake-level project by calling the `CMake project function <project-function-cmake>`.
-- Load the git version. This includes some magic which will automatically re-run cmake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
-- Include ``project_include.cmake`` files from any components which have them.
-- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library <add-library-cmake>` function to add a library and then adds source files, compile options, etc.
-- Add the final app executable to the build.
-- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
-
-Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
-
-Debugging CMake
----------------
-
-Some tips for debugging the esp-idf CMake-based build system:
-
-- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
-- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
-
-.. _warn-undefined-variables-cmake:
-
-Warning On Undefined Variables
-------------------------------
-
-By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
-
-If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
-
-Overriding Parts of the Project
--------------------------------
-
-project_include.cmake
-^^^^^^^^^^^^^^^^^^^^^
-
-For components that have build requirements that must be evaluated before any component CMakeLists
-files are evaluated, you can create a file called ``project_include.cmake`` in the
-component directory. This makefile is included when ``project.cmake`` is evaluating the entire project.
-
-``project_include.cmake`` files are used heavily inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
-
-Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
-
-Take great care when setting variables or targets in this file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
-
-KConfig.projbuild
-^^^^^^^^^^^^^^^^^
-
-This is an equivalent to ``project_include.cmake`` for `component configuration` KConfig files. If you want to include
-configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
-
-Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
-
-
-Configuration-Only Components
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
-
-If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
-
-Example Component CMakeLists
-============================
-
-Because the build environment tries to set reasonable defaults that will work most
-of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
-
-Here are some more advanced examples of component CMakeLists files.
-
-
-Adding conditional configuration
---------------------------------
-
-The configuration system can be used to conditionally compile some files
-depending on the options selected in the project configuration.
-
-
-``Kconfig``::
-
-    config FOO_ENABLE_BAR
-        bool "Enable the BAR feature."
-        help
-            This enables the BAR feature of the FOO component.
-
-``CMakeLists.txt``::
-
-    set(COMPONENT_SRCS "foo.c" "more_foo.c")
-
-    if(CONFIG_FOO_ENABLE_BAR)
-        list(APPEND COMPONENT_SRCS "bar.c")
-    endif(CONFIG_FOO_ENABLE_BAR)
-
-This example makes use of the CMake `if function <if-cmake>` and `list APPEND <list-cmake>` function.
-
-This can also be used to select or stub out an implementation, as such:
-
-``Kconfig``::
-
-    config ENABLE_LCD_OUTPUT
-        bool "Enable LCD output."
-        help
-            Select this if your board has a LCD.
-
-    config ENABLE_LCD_CONSOLE
-        bool "Output console text to LCD"
-        depends on ENABLE_LCD_OUTPUT
-        help
-            Select this to output debugging output to the lcd
-
-    config ENABLE_LCD_PLOT
-        bool "Output temperature plots to LCD"
-        depends on ENABLE_LCD_OUTPUT
-        help
-            Select this to output temperature plots
-
-
-``CMakeLists.txt``::
-
-    if(CONFIG_ENABLE_LCD_OUTPUT)
-       set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
-    else()
-       set(COMPONENT_SRCS lcd-dummy.c)
-    endif()
-
-    # We need font if either console or plot is enabled
-    if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_NEABLE_LCD_PLOT)
-      list(APPEND COMPONENT_SRCS "font.c")
-    endif()
-
-
-Source Code Generation
-----------------------
-
-Some components will have a situation where a source file isn't
-supplied with the component itself but has to be generated from
-another file. Say our component has a header file that consists of the
-converted binary data of a BMP file, converted using a hypothetical
-tool called bmp2h. The header file is then included in as C source
-file called graphics_lib.c::
-
-    COMPONENT_EXTRA_CLEAN := logo.h
-
-    add_custom_command(OUTPUT logo.h
-         COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
-         DEPENDS ${COMPONENT_PATH}/logo.bmp
-         VERBATIM)
-
-    add_custom_target(logo DEPENDS logo.h)
-    add_dependencies(${COMPONENT_NAME} logo)
-
-    set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
-         ADDITIONAL_MAKE_CLEAN_FILES logo.h)
-
-This answer is adapted from the `CMake FAQ entry <cmake-faq-generated-files>`, which contains some other examples that will also work with ESP-IDF builds.
-
-In this example, logo.h will be generated in the
-current directory (the build directory) while logo.bmp comes with the
-component and resides under the component path. Because logo.h is a
-generated file, it should be cleaned when make clean is called which
-why it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
-
-(Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
-
-If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
-the two components, to ensure that the component source files were always compiled in the correct order.
-
-Embedding Binary Data
----------------------
-
-Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
-
-You can set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving the names of the files to embed in this way::
-
-  set(COMPONENT_EMBED_FILES server_root_cert.der)
-
-Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string::
-
-  set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
-
-The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
-
-  extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
-  extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
-
-The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
-
-To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
-
-  target_add_binary_data(myproject.elf "main/data.bin" TEXT)
-
-Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
-
-For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
-
-
-Fully Overriding The Component Build Process
---------------------------------------------
-
-Obviously, there are cases where all these recipes are insufficient for a
-certain component, for example when the component is basically a wrapper
-around another third-party component not originally intended to be
-compiled under this build system. In that case, it's possible to forego
-the esp-idf build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
-
-  # External build process for quirc, runs in source dir and
-  # produces libquirc.a
-  externalproject_add(quirc_build
-      PREFIX ${COMPONENT_PATH}
-      SOURCE_DIR ${COMPONENT_PATH}/quirc
-      CONFIGURE_COMMAND ""
-      BUILD_IN_SOURCE 1
-      BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
-      INSTALL_COMMAND ""
-      )
-
-   # Add libquirc.a to the build process
-   #
-   add_library(quirc STATIC IMPORTED GLOBAL)
-   add_dependencies(quirc quirc_build)
-
-   set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
-        ${COMPONENT_PATH}/quirc/libquirc.a)
-   set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
-        ${COMPONENT_PATH}/quirc/lib)
-
-   set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
-        "${COMPONENT_PATH}/quirc/libquirc.a")
-
-(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
-
-- ``externalproject_add`` defines an external build system.
-  - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
-  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
-  - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
-
-- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
-- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
-
-ExternalProject dependencies, clean builds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-CMake has some unusual behaviour around external project builds:
-
-.. ADDITIONAL_MAKE_CLEAN_FILES_note:
-
-- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
-- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
-- Therefore, there are two alternative recommended ways to configure the external build command:
-  1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
-  2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
-
-The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
-
-.. _custom-sdkconfig-defaults-cmake:
-
-Custom sdkconfig defaults
-=========================
-
-For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
-
-To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
-
-
-Flash arguments
-===============
-
-There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
-
-After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
-
-- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
-- ``flash_app_args`` contains arguments to flash only the app.
-- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
-
-You can pass any of these flasher argument files to ``esptool.py`` as follows::
-
-  python esptool.py --chip esp32 write_flash @build/flash_project_args
-
-Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
-
-The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
-
-Building the Bootloader
-=======================
-
-The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
-
-The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
-
-The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
-
-Writing Pure CMake Components
-=============================
-
-The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
-
-However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
-
-Here is an example minimal "pure CMake" component CMakeLists file for a componen named ``json``::
-
-  add_library(json STATIC
-  cJSON/cJSON.c
-  cJSON/cJSON_Utils.c)
-
-  target_include_directories(json PUBLIC cJSON)
-
-- This is actually an equivalent version of the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
-- This file quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
-- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
-
-
-File Globbing & Incremental Builds
-==================================
-
-The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
-
-  set(COMPONENT_SRCDIRS library platform)
-
-The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
-
-  set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
-
-Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
-
-The tradeoff is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
-
-For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
-
-For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.)
-
-For project components (not part of ESP-IDF), there are a few options:
-
-- If keeping your project file in Git, ESP-IDF will automaticallytrack the Git revision and re-run CMake if the revision changes.
-- If some components are kept in a third git repo (not the project repo or ESP-IDF repo), you can add calls to the ``git_describe`` function to component CMakeLists to trigger re-runs of CMake.
-- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change.
-- Use ``COMPONENT_SRCS`` to list all source files in project components.
-
-The best option will depend on your particular project and its users.
-
-Migrating from ESP-IDF GNU Make System
-======================================
-
-Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_SRCS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
-
-However, some features are significantly different or removed in the CMake-based system:
-
-The following variables no longer exist in the CMake-based build system:
-
-- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
-- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the user. The name of the component library can no longer be overriden by the user.
-- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <language-variables-cmake>`_.
-- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
-- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
-- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically for files like linker scripts.
-- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo.
-- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
-- ``COMPONENT_OBJS``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``.
-- ``COMPONENT_EXTRA_CLEAN``: Set property `ADDITIONAL_MAKE_CLEAN_FILES` instead but note `CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
-- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See `Fully Overriding The Component CMakeLists` for full details.
-- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
-- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use CMake_ commands instead. See `Controlling Component Compilation`_.
-
-The following variables no longer have default values:
-
-- ``COMPONENT_SRCDIRS``
-- ``COMPONENT_ADD_INCLUDEDIRS``
-
-It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
-
-Build System Metadata
-=====================
-
-For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
-
-- ``project_description.json`` contains some general information about the project, configured paths, etc.
-- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`.
-- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
-
-.. _esp-idf-template: https://github.com/espressif/esp-idf-template
-.. _cmake: https://cmake.org
-.. _ninja: https://ninja-build.org
-.. _esptool.py: https://github.com/espressif/esptool/#readme
-.. _CMake v3.5 documentation_: https://cmake.org/cmake/help/v3.5/index.html
-.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
-.. _add_compile_options-cmake: https://cmake.org/cmake/help/v3.5/command/add_compile_options.html
-.. _if-cmake: https://cmake.org/cmake/help/v3.5/command/if.html
-.. _string-cmake: https://cmake.org/cmake/help/v3.5/command/string.html
-.. _cmake-faq-generated-files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
-.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
-.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
-.. _language-variables-cmake: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
-.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
-.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
-.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
-.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
-.. _quirc: https://github.com/dlbeer/quirc
-
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index 8d3830c8b..28789b307 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -1,17 +1,19 @@
 Build System
 ************
 
-This document explains the Espressif IoT Development Framework build system and the
-concept of "components"
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
-Read this document if you want to know how to organise a new ESP-IDF project.
+This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components".
 
-We recommend using the esp-idf-template_ project as a starting point for your project.
+Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system.
 
-Using the Build System
-======================
+For information relating to the older GNU Make-based build system, see here:
 
-The esp-idf README file contains a description of how to use the build system to build your project.
+.. toctree::
+    :maxdepth: 1
+
+    gnu-make-build-system
 
 Overview
 ========
@@ -19,7 +21,7 @@ Overview
 An ESP-IDF project can be seen as an amalgamation of a number of components.
 For example, for a webserver that shows the current humidity, there could be:
 
-- The ESP32 base libraries (libc, rom bindings etc)
+- The ESP32 base libraries (libc, ROM bindings, etc)
 - The WiFi drivers
 - A TCP/IP stack
 - The FreeRTOS operating system
@@ -28,425 +30,456 @@ For example, for a webserver that shows the current humidity, there could be:
 - Main code tying it all together
 
 ESP-IDF makes these components explicit and configurable. To do that,
-when a project is compiled, the build environment will look up all the
+when a project is compiled, the build system will look up all the
 components in the ESP-IDF directories, the project directories and
 (optionally) in additional custom component directories. It then
 allows the user to configure the ESP-IDF project using a a text-based
 menu system to customize each component. After the components in the
-project are configured, the build process will compile the project.
+project are configured, the build system will compile the project.
 
 Concepts
 --------
 
 - A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader.
 
-- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
+- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
 
 - An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
 
-- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places.
+- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
 
 Some things are not part of the project:
 
 - "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
 
-- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration.
+- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
 
+Using the Build System
+======================
+
+.. _idf.py:
+
+idf.py
+------
+
+The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
+
+- CMake_, which configures the project to be built
+- A command line build tool (either Ninja_ build or `GNU Make`)
+- `esptool.py`_ for flashing ESP32.
+
+The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
+
+``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
+
+Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
+
+- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
+- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
+  - Create the build directory if needed. The subdirectory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
+  - Run CMake_ as necessary to configure the project and generate build files for the main build tool.
+  - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
+  Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
+- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
+- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
+- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
+- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
+- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`/get-started/idf-monitor` for more details about using the monitor.
+
+Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
+
+Advanced Commands
+^^^^^^^^^^^^^^^^^
+
+- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
+- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
+- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
+- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
+
+The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
+
+Using CMake Directly
+--------------------
+
+:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
+
+.. highlight:: bash
+
+When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt)::
+
+  mkdir -p build
+  cd build
+  cmake .. -G Ninja   # or 'GNU Make'
+  ninja
+
+In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: runnning ``ninja`` actually builds the project.
+
+It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguring.
+
+If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
+
+.. note::
+   If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
+
+Using CMake in an IDE
+---------------------
+
+You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
+
+When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
 
 Example Project
----------------
+===============
+
+.. highlight:: none
 
 An example project directory tree might look like this::
 
     - myProject/
-                 - Makefile
+                 - CMakeLists.txt
                  - sdkconfig
-                 - components/ - component1/ - component.mk
+                 - components/ - component1/ - CMakeLists.txt
                                              - Kconfig
                                              - src1.c
-                               - component2/ - component.mk
+                               - component2/ - CMakeLists.txt
                                              - Kconfig
                                              - src1.c
                                              - include/ - component2.h
                  - main/       - src1.c
                                - src2.c
-                               - component.mk
 
                  - build/
 
 This example "myProject" contains the following elements:
 
-- A top-level project Makefile. This Makefile set the ``PROJECT_NAME`` variable and (optionally) defines
-  other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which
-  implements the rest of the ESP-IDF build system.
+- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
+  implements the rest of the build system. Finally, it sets the project name and defines the project.
 
 - "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
 
 - Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
 
-- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places.
+- "main" directory is a special "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
 
-- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
+- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
 
-Component directories contain a component makefile - ``component.mk``. This may contain variable definitions
-to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.
+Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
+to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
 
-Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`.
+Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
 
-Project Makefiles
------------------
+Project CMakeLists File
+=======================
 
-Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal.
+Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
 
-Minimal Example Makefile
-^^^^^^^^^^^^^^^^^^^^^^^^
+Minimal Example CMakeLists
+--------------------------
 
-::
+.. highlight:: cmake
 
-   PROJECT_NAME := myProject
-   
-   include $(IDF_PATH)/make/project.mk
+Minimal project::
+
+      cmake_minimum_required(VERSION 3.5)
+
+      set(MAIN_SRCS main/src1.c main/src2.c)
+
+      include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+      project(myProject)
 
 
-Mandatory Project Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Mandatory Parts
+---------------
+
+The inclusion of these four lines, in the order shown above, is necessary for every project:
+
+- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
+- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged.
+
+  It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
+
+   ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
+- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
+- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
 
-- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf.
 
 Optional Project Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
 
-These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details.
+These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
 
-- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces.
-- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``.
-- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
-- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components.
-- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories.
-- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size.
+- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
+- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
+- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list can be very short.
+- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically added to every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this variable is set to the minimal set of core "system" components needed for any ESP-IDF project. Usually, you would not change this variable in your project.
 
-Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``.
+Any paths in these variables can be absolute paths, or set relative to the project directory.
 
-These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile.
+To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
 
-Component Makefiles
--------------------
+Component CMakeLists Files
+==========================
 
-Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
+Each project contains one or more components. Components can be part of esp-idf, part of the project's own components directory, or added from custom component directories (see above).
 
-A component is any directory that contains a ``component.mk`` file.
+A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
 
 Searching for Components
 ------------------------
 
-The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components.
+The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose subdirectories are components.
 
-Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories.
+When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
 
 Multiple components with the same name
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------------
 
-When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the 
-idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories
-contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components 
-with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. 
-If used in this way, the esp-idf directory itself can remain untouched.
+When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
+contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components
+with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
+If used in this way, the ESP-IDF directory itself can remain untouched.
 
-Minimal Component Makefile
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Minimal Component CMakeLists
+----------------------------
 
-The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set:
+.. highlight:: cmake
 
-- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library
-- A sub-directory "include" will be added to the global include search path for all other components.
-- The component library will be linked into the project app.
+The minimal component ``CMakeLists.txt`` file is as follows::
 
-See `example component makefiles`_ for more complete component makefile examples.
+  set(COMPONENT_SRCDIRS ".")
+  set(COMPONENT_ADD_INCLUDEDIRS "include")
+  register_component()
 
-Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process.
+- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
+- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for any component which requires this component, and also the main source files.
+- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if function <cmake if_>`_ or similar), this component will not be part of the build.
 
-.. component variables:
+Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
+
+See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
+
+.. _component variables:
 
 Preset Component Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------
 
-The following component-specific variables are available for use inside ``component.mk``, but should not be modified:
+The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
 
-- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces.
-- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory.
-- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory.
-- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``.
+- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
+- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
 
-The following variables are set at the project level, but exported for use in the component build:
+The following variables are set at the project level, but available for use in component CMakeLists:
 
 - ``PROJECT_NAME``: Name of the project, as set in project Makefile
-- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile.
-- ``COMPONENTS``: Name of all components that are included in this build.
-- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``.
-- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
-- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
-- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
+- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
+- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
+- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
+- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
 
-If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
+If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
 
-Optional Project-Wide Component Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for
+  all other components which require this one. If an include directory is only needed to compile this specific component,
+  add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
+- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If this component has a header file in a ``COMPONENT_ADD_INCLUDEDIRS`` directory that includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
 
-The following variables can be set inside ``component.mk`` to control build settings across the entire project:
+  The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
 
-- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
-  directory, which will be added to the include search path for
-  all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile
-  this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
-- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for
-  the app executable. Defaults to ``-l$(COMPONENT_NAME)``.  If
-  adding pre-compiled libraries to this directory, add them as
-  absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
-- ``COMPONENT_REQUIRES``: Optional list of component names that should
-  be compiled before this component. This is not necessary for
-  link-time dependencies, because all component include directories
-  are available at all times. It is necessary if one component
-  generates an include file which you then want to include in another
-  component. Most components do not need to set this variable.
-- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths
-  to files which should trigger a re-link of the ELF file if they change.
-  Typically used for linker script files and binary libraries. Most components do
-  not need to set this variable.
-
-The following variable only works for components that are part of esp-idf itself:
-
-- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths
-  (relative to COMPONENT_PATH) used by the component. These will be
-  checked (and initialised if necessary) by the build process. This
-  variable is ignored if the component is outside the IDF_PATH
-  directory.
+  If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
 
+  See `Component Requirements` for more details.
 
 Optional Component-Specific Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+-------------------------------------
 
 The following variables can be set inside ``component.mk`` to control the build of that component:
 
 - ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
   the component directory, which will be added to the include search
   path for this component's source files only.
-- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when
-  compiling the component's source files. These will be prefixed with
-  '-I' and passed as-is to the compiler.  Similar to the
-  ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not
-  expanded relative to the component directory.
-- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
-  component directory, which will be searched for source files (``*.cpp``,
-  ``*.c``, ``*.S``). Defaults to '.', ie the component directory
-  itself. Override this to specify a different list of directories
-  which contain source files.
-- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o
-  file for each source file that is found in ``COMPONENT_SRCDIRS``.
-  Overriding this list allows you to exclude source files in
-  ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See
-  `Specifying source files`
-- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build
-  directory, of any files that are generated using custom make rules
-  in the component.mk file and which need to be removed as part of
-  ``make clean``. See `Source Code Generation`_ for an example.
-- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These
-  targets allow you to fully override the default build behaviour for
-  the component. See `Fully Overriding The Component Makefile`_ for
-  more details.
-- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component
-  produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built),
-  and most other component variables are ignored. This flag is used for IDF
-  internal components which contain only ``KConfig.projbuild`` and/or
-  ``Makefile.projbuild`` files to configure the project, but no source files.
-- ``CFLAGS``: Flags passed to the C compiler. A default set of
-  ``CFLAGS`` is defined based on project settings. Component-specific
-  additions can be made via ``CFLAGS +=``. It is also possible
-  (although not recommended) to override this variable completely for
-  a component.
-- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp
-  and .S files). A default set of ``CPPFLAGS`` is defined based on
-  project settings. Component-specific additions can be made via
-  ``CPPFLAGS +=``. It is also possible (although not recommended) to
-  override this variable completely for a component.
-- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of
-  ``CXXFLAGS`` is defined based on project
-  settings. Component-specific additions can be made via ``CXXFLAGS
-  +=``. It is also possible (although not recommended) to override
-  this variable completely for a component.
+- ``COMPONENT_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details.
+- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``,
+  ``*.c``, ``*.S``). Set this to specify a list of directories which contain source files.
+- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
+  If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``.
 
-To apply compilation flags to a single source file, you can add a variable override as a target, ie::
+Controlling Component Compilation
+---------------------------------
 
-  apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
+.. highlight:: cmake
+
+To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
+
+  component_compile_options(-Wno-unused-variable)
+
+This is a wrapper around the CMake `target_compile_options`_ command.
+
+To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
+
+    set_source_files_properties(mysrc.c
+        PROPERTIES COMPILE_FLAGS
+        -Wno-unused-variable
+    )
 
 This can be useful if there is upstream code that emits warnings.
 
-Component Configuration
------------------------
+When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
 
-Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
-configuration settings to add to the "make menuconfig" for this component.
+Component Configuration
+=======================
+
+Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains
+configuration settings to add to the configuration menu for this component.
 
 These settings are found under the "Component Settings" menu when menuconfig is run.
 
-To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.
+To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with esp-idf.
 
 For an example, see `Adding conditional configuration`_.
 
 Preprocessor Definitions
-------------------------
+========================
 
-ESP-IDF build systems adds the following C preprocessor definitions on the command line:
+The ESP-IDF build system adds the following C preprocessor definitions on the command line:
 
 - ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
-- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details.
+- ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
 
-Build Process Internals
+Component Requirements
+======================
+
+When compiling each component, the ESP-IDF build system recursively evaluates its components.
+
+Each component's source file is compiled with these include path directories:
+
+- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
+- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
+- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
+
+When writing a component
+------------------------
+
+- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
+- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
+- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
+- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
+- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
+
+When creating a project
 -----------------------
 
-Top Level: Project Makefile
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- By default, every component is included in the build.
+- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
+  - Components mentioned explicitly in ``COMPONENTS``.
+  - Those components' requirements (evaluated recursively).
+  - The "common" components that every component depends on.
+- Setting ``COMPONENTS`` to the minimal list of components you need can significantly reduce your project's compile time.
+- When compiling the project's source files (``MAIN_SRCS``), the public header directories (``COMPONENT_ADD_INCLUDEDIRS`` list) of all components included in the build are available.
 
-- "make" is always run from the project directory and the project makefile, typically named Makefile.
-- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables`
-- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic.
-- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top.
-- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`.
-- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top.
-- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. 
-- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets.
-- In order to compile each component, a recursive make is performed for the component makefile.
+.. _component-requirements-implementation:
 
-To better understand the project make process, have a read through the ``project.mk`` file itself.
+Requirements in the build system implementation
+-----------------------------------------------
 
-Second Level: Component Makefiles
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Very early in the cmake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
+- The main cmake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
+- Configuration is then evaluated for the components included in the build.
+- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
 
-- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile.
-- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component.
-- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``.
-- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these.
-- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file.
-- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration.
+Build Process Internals
+=======================
 
-To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf.
+For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`.
 
-Running Make Non-Interactively
-------------------------------
+project.cmake contents
+----------------------
 
-When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable).
+When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environmenmt.
 
-Setting ``BATCH_BUILD`` implies the following:
+It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality.
 
-- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``.
-- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item.
-- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails.
+project function
+----------------
 
-Debugging The Make Process
---------------------------
+The custom ``project()`` function performs the following steps:
 
-Some tips for debugging the esp-idf build system:
+- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above<component-requirements-implementation>`).
+- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
+- Loads the project configuration from the ``sdkconfig`` file and produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
+- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
+- Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
+- Load the git version. This includes some magic which will automatically re-run cmake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
+- Include ``project_include.cmake`` files from any components which have them.
+- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
+- Add the final app executable to the build.
+- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
 
-- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make.
-- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands.
-- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built.
-- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile.
+Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
 
-For more debugging tips and general make information, see the `GNU Make Manual`.
+Debugging CMake
+---------------
+
+Some tips for debugging the esp-idf CMake-based build system:
+
+- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
+- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
 
 .. _warn-undefined-variables:
 
 Warning On Undefined Variables
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------
 
-By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names.
+By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
 
-If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`.
-
-Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles.
+If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
 
 Overriding Parts of the Project
 -------------------------------
 
-Makefile.projbuild
-^^^^^^^^^^^^^^^^^^
+project_include.cmake
+^^^^^^^^^^^^^^^^^^^^^
 
-For components that have build requirements that must be evaluated in the top-level
-project make pass, you can create a file called ``Makefile.projbuild`` in the
-component directory. This makefile is included when ``project.mk`` is evaluated.
+For components that have build requirements which must be evaluated before any component CMakeLists
+files are evaluated, you can create a file called ``project_include.cmake`` in the
+component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
 
-For example, if your component needs to add to CFLAGS for the entire
-project (not just for its own source files) then you can set
-``CFLAGS +=`` in Makefile.projbuild.
+``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
 
-``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
+Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
 
-Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details.
-
-Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components!
+Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
 
 KConfig.projbuild
 ^^^^^^^^^^^^^^^^^
 
-This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include
-configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file.
+This is an equivalent to ``project_include.cmake`` for `component configuration` KConfig files. If you want to include
+configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
 
 Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
 
 
-Makefile.componentbuild
-^^^^^^^^^^^^^^^^^^^^^^^
-
-For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions
-into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included
-in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're
-included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component.
-
 Configuration-Only Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component.
+Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
 
-Example Component Makefiles
----------------------------
+If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
+
+Example Component CMakeLists
+============================
 
 Because the build environment tries to set reasonable defaults that will work most
-of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.
+of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
 
-Here are some more advanced examples of ``component.mk`` makefiles:
-
-
-Adding source directories
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, sub-directories are ignored. If your project has sources in sub-directories
-instead of in the root of the component then you can tell that to the build
-system by setting ``COMPONENT_SRCDIRS``::
-
-    COMPONENT_SRCDIRS := src1 src2
-
-This will compile all source files in the src1/ and src2/ sub-directories
-instead.
-
-Specifying source files
-^^^^^^^^^^^^^^^^^^^^^^^
-
-The standard component.mk logic adds all .S and .c files in the source
-directories as sources to be compiled unconditionally. It is possible
-to circumvent that logic and hard-code the objects to be compiled by
-manually setting the ``COMPONENT_OBJS`` variable to the name of the
-objects that need to be generated::
-
-    COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
-    COMPONENT_SRCDIRS := . thing anotherthing
-
-Note that ``COMPONENT_SRCDIRS`` must be set as well.
+Here are some more advanced examples of component CMakeLists files.
 
 Adding conditional configuration
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+--------------------------------
 
 The configuration system can be used to conditionally compile some files
-depending on the options selected in ``make menuconfig``. For this, ESP-IDF
-has the compile_only_if and compile_only_if_not macros:
+depending on the options selected in the project configuration.
+
+.. highlight:: none
 
 ``Kconfig``::
 
@@ -455,17 +488,15 @@ has the compile_only_if and compile_only_if_not macros:
         help
             This enables the BAR feature of the FOO component.
 
-``component.mk``::
+``CMakeLists.txt``::
 
-    $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
+    set(COMPONENT_SRCS "foo.c" "more_foo.c")
 
+    if(CONFIG_FOO_ENABLE_BAR)
+        list(APPEND COMPONENT_SRCS "bar.c")
+    endif(CONFIG_FOO_ENABLE_BAR)
 
-As can be seen in the example, the ``compile_only_if`` macro takes a condition and a 
-list of object files as parameters. If the condition is true (in this case: if the
-BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will
-always be compiled. The opposite goes as well: if the condition is not true, bar.o 
-will never be compiled. ``compile_only_if_not`` does the opposite: compile if the 
-condition is false, not compile if the condition is true.
+This example makes use of the CMake `if function <cmake if_>`_ and `list APPEND <cmake list_>`_ function.
 
 This can also be used to select or stub out an implementation, as such:
 
@@ -488,28 +519,24 @@ This can also be used to select or stub out an implementation, as such:
         help
             Select this to output temperature plots
 
+.. highlight:: cmake
 
-``component.mk``::
+``CMakeLists.txt``::
 
-    # If LCD is enabled, compile interface to it, otherwise compile dummy interface
-    $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
-    $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
+    if(CONFIG_ENABLE_LCD_OUTPUT)
+       set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
+    else()
+       set(COMPONENT_SRCS lcd-dummy.c)
+    endif()
 
-    #We need font if either console or plot is enabled
-    $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
+    # We need font if either console or plot is enabled
+    if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_NEABLE_LCD_PLOT)
+      list(APPEND COMPONENT_SRCS "font.c")
+    endif()
 
-Note the use of the Make 'or' function to include the font file. Other substitution functions,
-like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also 
-be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains 
-only whitespace to be false while a variable with any non-whitespace in it is true.
-
-(Note: Older versions of this document advised conditionally adding object file names to
-``COMPONENT_OBJS``. While this still is possible, this will only work when all object 
-files for a component are named explicitely, and will not clean up deselected object files
-in a ``make clean`` pass.)
 
 Source Code Generation
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 Some components will have a situation where a source file isn't
 supplied with the component itself but has to be generated from
@@ -518,104 +545,304 @@ converted binary data of a BMP file, converted using a hypothetical
 tool called bmp2h. The header file is then included in as C source
 file called graphics_lib.c::
 
-    COMPONENT_EXTRA_CLEAN := logo.h
+    add_custom_command(OUTPUT logo.h
+         COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
+         DEPENDS ${COMPONENT_PATH}/logo.bmp
+         VERBATIM)
 
-    graphics_lib.o: logo.h
+    add_custom_target(logo DEPENDS logo.h)
+    add_dependencies(${COMPONENT_NAME} logo)
 
-    logo.h: $(COMPONENT_PATH)/logo.bmp
-        bmp2h -i $^ -o $@
+    set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
+         ADDITIONAL_MAKE_CLEAN_FILES logo.h)
 
+This answer is adapted from the `CMake FAQ entry <cmake faq generated files_>`_, which contains some other examples that will also work with ESP-IDF builds.
 
-In this example, graphics_lib.o and logo.h will be generated in the
+In this example, logo.h will be generated in the
 current directory (the build directory) while logo.bmp comes with the
 component and resides under the component path. Because logo.h is a
-generated file, it needs to be cleaned when make clean is called which
-why it is added to the COMPONENT_EXTRA_CLEAN variable.
+generated file, it should be cleaned when the project is cleaned. For this reason
+it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
 
-Cosmetic Improvements
-^^^^^^^^^^^^^^^^^^^^^
+(Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
 
-Because logo.h is a generated file, it needs to be cleaned when make
-clean is called which why it is added to the COMPONENT_EXTRA_CLEAN
-variable.
-
-Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be
-generated before ``graphics_lib.c`` is compiled.
-
-If a a source file in another component included ``logo.h``, then this
-component's name would have to be added to the other component's
-``COMPONENT_REQUIRES`` list to ensure that the components were built
-in-order.
+If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
+the two components, to ensure that the component source files were always compiled in the correct order.
 
 Embedding Binary Data
-^^^^^^^^^^^^^^^^^^^^^
+---------------------
 
 Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
 
-You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way::
+You can set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving the names of the files to embed in this way::
 
-  COMPONENT_EMBED_FILES := server_root_cert.der
+  set(COMPONENT_EMBED_FILES server_root_cert.der)
 
-Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string::
+Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string::
 
-  COMPONENT_EMBED_TXTFILES := server_root_cert.pem
+  set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
+
+.. highlight:: c
 
 The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
 
   extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
   extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
 
-The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
+The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
+
+.. highlight:: cmake
+
+To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
+
+  target_add_binary_data(myproject.elf "main/data.bin" TEXT)
+
+Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
 
 For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
 
+.. _component-build-full-override:
 
-Fully Overriding The Component Makefile
----------------------------------------
+Fully Overriding The Component Build Process
+--------------------------------------------
+
+.. highlight:: cmake
 
 Obviously, there are cases where all these recipes are insufficient for a
 certain component, for example when the component is basically a wrapper
 around another third-party component not originally intended to be
 compiled under this build system. In that case, it's possible to forego
-the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and
-possibly  COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk``
-target. The build target can do anything as long as it creates
-$(COMPONENT_LIBRARY) for the project make process to link into the app binary.
+the esp-idf build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
 
-(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable
-is overridden then the component can instruct the linker to link other binaries instead.)
+  # External build process for quirc, runs in source dir and
+  # produces libquirc.a
+  externalproject_add(quirc_build
+      PREFIX ${COMPONENT_PATH}
+      SOURCE_DIR ${COMPONENT_PATH}/quirc
+      CONFIGURE_COMMAND ""
+      BUILD_IN_SOURCE 1
+      BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
+      INSTALL_COMMAND ""
+      )
 
+   # Add libquirc.a to the build process
+   #
+   add_library(quirc STATIC IMPORTED GLOBAL)
+   add_dependencies(quirc quirc_build)
 
-.. _esp-idf-template: https://github.com/espressif/esp-idf-template
-.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
+   set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
+        ${COMPONENT_PATH}/quirc/libquirc.a)
+   set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
+        ${COMPONENT_PATH}/quirc/lib)
 
+   set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
+        "${COMPONENT_PATH}/quirc/libquirc.a")
+
+(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
+
+- ``externalproject_add`` defines an external build system.
+  - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
+  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
+  - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
+
+- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
+- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
+
+.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
+
+ExternalProject dependencies, clean builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CMake has some unusual behaviour around external project builds:
+
+- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
+- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
+- Therefore, there are two alternative recommended ways to configure the external build command:
+
+    1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
+    2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
+
+The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
 
 .. _custom-sdkconfig-defaults:
 
 Custom sdkconfig defaults
--------------------------
+=========================
 
-For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch.
+For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
 
 To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
 
 
-Save flash arguments
---------------------
+Flash arguments
+===============
 
-There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments::
+There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
 
-    --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
+After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
 
-Then use flash arguments as the arguemnts for esptool write_flash arguments::
+- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
+- ``flash_app_args`` contains arguments to flash only the app.
+- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
 
-    python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
+.. highlight:: bash
+
+You can pass any of these flasher argument files to ``esptool.py`` as follows::
+
+  python esptool.py --chip esp32 write_flash @build/flash_project_args
+
+Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
+
+The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
 
 Building the Bootloader
 =======================
 
-The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build.
+The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
 
-The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project.
+The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
 
-This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details.
+The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
+
+Writing Pure CMake Components
+=============================
+
+The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
+
+However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
+
+.. highlight:: cmake
+
+Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``::
+
+  add_library(json STATIC
+  cJSON/cJSON.c
+  cJSON/cJSON_Utils.c)
+
+  target_include_directories(json PUBLIC cJSON)
+
+- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
+- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
+- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
+
+
+File Globbing & Incremental Builds
+==================================
+
+.. highlight:: cmake
+
+The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
+
+  set(COMPONENT_SRCDIRS library platform)
+
+The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
+
+  set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
+
+Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
+
+The tradeoff is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
+
+For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
+
+For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.)
+
+For project components (not part of ESP-IDF), there are a few options:
+
+- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes.
+- If some components are kept in a third git repo (not the project repo or ESP-IDF repo), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to trigger re-runs of CMake.
+- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change.
+- Use ``COMPONENT_SRCS`` to list all source files in project components.
+
+The best option will depend on your particular project and its users.
+
+.. _gnu-make-to-cmake:
+
+Migrating from ESP-IDF GNU Make System
+======================================
+
+Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_SRCS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
+
+Automatic Conversion Tool
+-------------------------
+
+.. highlight:: bash
+
+An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this::
+
+    $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir
+
+The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH.
+
+The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files.
+
+It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables.
+
+The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand.
+
+
+No Longer Available in CMake
+----------------------------
+
+Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
+
+- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
+- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the user. The name of the component library can no longer be overriden by the user.
+- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
+- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
+- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
+- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically for files like linker scripts.
+- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo.
+- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
+- ``COMPONENT_OBJS``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``.
+- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
+- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
+- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_.
+
+
+No Default Values
+-----------------
+
+The following variables no longer have default values:
+
+- ``COMPONENT_SRCDIRS``
+- ``COMPONENT_ADD_INCLUDEDIRS``
+
+No Longer Necessary
+-------------------
+
+It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
+
+Build System Metadata
+=====================
+
+For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+
+- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
+- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
+- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
+- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
+- ``sdkconfig.json`` is a JSON-formatted version of the project configuration values.
+
+.. _esp-idf-template: https://github.com/espressif/esp-idf-template
+.. _cmake: https://cmake.org
+.. _ninja: https://ninja-build.org
+.. _esptool.py: https://github.com/espressif/esptool/#readme
+.. _CMake v3.5 documentation_: https://cmake.org/cmake/help/v3.5/index.html
+.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
+.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/project.html
+.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html
+.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html
+.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html
+.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html
+.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html
+.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
+.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
+.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
+.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
+.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
+.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
+.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
+.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
+.. _quirc: https://github.com/dlbeer/quirc
diff --git a/docs/en/api-guides/cmake-preview-index.rst b/docs/en/api-guides/cmake-preview-index.rst
deleted file mode 100644
index 22e94c67a..000000000
--- a/docs/en/api-guides/cmake-preview-index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-CMake-Based Build System Preview
-********************************
-
-.. toctree::
-   :maxdepth: 1
-
-   Getting Started <../get-started/index-cmake>
-   Linux Setup <../get-started/linux-setup-cmake>
-   Windows Setup <../get-started/windows-setup-cmake>
-   Build System Guide <build-system-cmake>
diff --git a/docs/en/api-guides/console.rst b/docs/en/api-guides/console.rst
index 490c9948d..c012c49d1 100644
--- a/docs/en/api-guides/console.rst
+++ b/docs/en/api-guides/console.rst
@@ -15,7 +15,7 @@ Line editing
 
 Line editing feature lets users compose commands by typing them, erasing symbols using 'backspace' key, navigating within the command using left/right keys, navigating to previously typed commands using up/down keys, and performing autocompletion using 'tab' key. 
 
-.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are  GNU screen, minicom, and idf_monitor.py (which can be invoked using ``make monitor`` from project directory).
+.. note:: This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running get_started/console example instead of a command prompt (``[esp32]>``), it means that the serial monitor does not support escape sequences. Programs which are known to work are  GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
 
 Here is an overview of functions provided by `linenoise`_ library.
 
diff --git a/docs/en/api-guides/core_dump.rst b/docs/en/api-guides/core_dump.rst
index 47cfd89c0..ce6a1afad 100644
--- a/docs/en/api-guides/core_dump.rst
+++ b/docs/en/api-guides/core_dump.rst
@@ -16,7 +16,7 @@ ESP-IDF provides special script `espcoredump.py` to help users to retrieve and a
 Configuration
 -------------
 
-There are a number of core dump related configuration options which user can choose in configuration menu of the application (`make menuconfig`).
+There are a number of core dump related configuration options which user can choose in configuration menu of the application (`idf.py menuconfig`).
 
 1. Core dump data destination (`Components -> ESP32-specific config -> Core dump destination`):
 
@@ -81,6 +81,6 @@ Generic command syntax:
     * --gdb,-g GDB.                 Path to gdb to use for data retrieval.
     * --core,-c CORE.               Path to core dump file to use (if skipped core dump will be read from flash).
     * --core-format,-t CORE_FORMAT. Specifies that file passed with "-c" is an ELF ("elf"), dumped raw binary ("raw") or base64-encoded ("b64") format.
-    * --off,-o OFF.                 Ofsset of coredump partition in flash (type "make partition_table" to see it).
+    * --off,-o OFF.                 Ofsset of coredump partition in flash (type "idf.py partition_table" to see it).
     * --save-core,-s SAVE_CORE.     Save core to file. Othwerwise temporary core file will be deleted. Ignored with "-c".
     * --print-mem,-m                Print memory dump. Used only with "info_corefile".
diff --git a/docs/en/api-guides/gnu-make-build-system.rst b/docs/en/api-guides/gnu-make-build-system.rst
new file mode 100644
index 000000000..1f9c5b9bd
--- /dev/null
+++ b/docs/en/api-guides/gnu-make-build-system.rst
@@ -0,0 +1,51 @@
+GNU Make Build System
+*********************
+
+This document contains a "cheat sheet" for users of the older ESP-IDF GNU Make build system and the newer CMake build system.
+
+Currently, this version of ESP-IDF contains support for both build systems, and either build system can be used. However, the rest of the documentation for this version has been updated for the CMake build system.
+
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view dedicated documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+
+Dependencies
+============
+
+For Linux & Mac OS, the dependencies for the GNU Make and CMake-based build systems are very similar. The only additional tool required for GNU Make is ``make`` 3.81 or newer. This is pre-installed on Mac OS and can be installed on Linux via the distribution package manager.
+
+For Windows, the requirements are different as the GNU Make based build system requires MSYS2 for a Unix compatibility layer. Consult the Getting Started docs for IDF v3.0 for steps to set up MSYS2.
+
+Cheat Sheet
+===========
+
+Equivalents between GNU make-based build system commands and the CMake-based build system:
+
+====================  ==================  =================
+Summary               CMake-based         GNU Make based
+====================  ==================  =================
+Configure project     idf.py menuconfig   make menuconfig
+Build project         idf.py build        make
+Flash project         idf.py flash        make flash
+Monitor project       idf.py monitor      make monitor
+Clean project         idf.py fullclean    make clean
+====================  ==================  =================
+
+To override the default build directory:
+
+- CMake based: ``idf.py -b (directory) build``
+- GNU Make based: ``make BUILD_DIR_BASE=(directory)``.
+
+To set the serial port for flashing/monitoring:
+
+- CMake based: ``idf.py -p (port) flash``
+- GNU Make based: ``make flash ESPPORT=/dev/ttyUSB0``, or set in ``menuconfig``.
+
+To set the baud rate for flashing:
+
+- CMake based: ``idf.py -b 921600 flash``
+- GNU Make based: ``make flash ESPBAUD=921600``, or set in ``menuconfig``.
+
+Porting GNU Make Based Components to CMake
+==========================================
+
+See :ref:`gnu-make-to-cmake`.
diff --git a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
index 12e5560b0..e7d6f5dfa 100644
--- a/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
+++ b/docs/en/api-guides/jtag-debugging/setup-openocd-windows.rst
@@ -7,7 +7,7 @@ Set up OpenOCD
 ==============
 
 
-OpenOCD for Windows / MSYS2 is available for download from Github:
+OpenOCD for Windows is available for download from Github:
 
 https://github.com/espressif/openocd-esp32/releases
 
@@ -16,7 +16,7 @@ Download latest release archive with `win32` in its name, for example `openocd-e
 Extract the downloaded file in ``~/esp/`` directory.
 
     cd ~/esp
-    unzip /c/Users/<user>/Downloads/openocd-esp32-win32-<version>.zip 
+    unzip /c/Users/<user>/Downloads/openocd-esp32-win32-<version>.zip
 
 Next Steps
 ==========
diff --git a/docs/en/get-started/add-idf_path-to-profile-cmake.rst b/docs/en/get-started/add-idf_path-to-profile-cmake.rst
deleted file mode 100644
index b1f1247d1..000000000
--- a/docs/en/get-started/add-idf_path-to-profile-cmake.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-Add IDF_PATH & idf.py PATH to User Profile
-==========================================
-
-.. note::
-   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<add-idf_path-to-profile>`.
-
-To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
-
-- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
-- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
-
-To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
-
-.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
-
-.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
-
-.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
-
-.. _add-paths-to-profile-windows-cmake:
-
-Windows
--------
-
-To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
-
-On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
-
-You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
-
-- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``.
-- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
-
-If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
-
-
-.. _add-idf_path-to-profile-linux-macos-cmake:
-
-Linux and MacOS
----------------
-
-Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file::
-
-    export IDF_PATH=~/esp/esp-idf
-    export PATH="$PATH:$IDF_PATH/tools"
-
-Log off and log in back to make this change effective.
-
-.. note::
-
-    If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
-
-Run the following command to check if ``IDF_PATH`` is set::
-
-    printenv IDF_PATH
-
-The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
-
-To verify idf.py is now on the ``PATH``, you can run the following::
-
-  which idf.py
-
-A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
-
-If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
-
-    export IDF_PATH=~/esp/esp-idf
-    export PATH="$PATH:$IDF_PATH/tools"
-
-If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst
index 60ca43481..f775f901f 100644
--- a/docs/en/get-started/add-idf_path-to-profile.rst
+++ b/docs/en/get-started/add-idf_path-to-profile.rst
@@ -1,39 +1,37 @@
-Add IDF_PATH to User Profile
-============================
+Add IDF_PATH & idf.py PATH to User Profile
+==========================================
 
-To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
+To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
 
-.. _add-idf_path-to-profile-windows:
+- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
+- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
+
+To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
+
+.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
+
+.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
+
+.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
+
+.. _add-paths-to-profile-windows:
 
 Windows
 -------
 
-The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
+To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
 
-#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
+On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
 
-#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
+You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
 
-#. Add the ``export`` command to the script file, e.g.::
+- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``.
+- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
 
-       export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
-
-   Remember to replace back-slashes with forward-slashes in the original Windows path.
-
-#. Save the script file.
-
-#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
-
-       printenv IDF_PATH
-
-   The path previusly entered in the script file should be printed out.
-
-If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
-
-    export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
-
-If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. 
+If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
 
 
 .. _add-idf_path-to-profile-linux-macos:
@@ -41,11 +39,12 @@ If you got here from section :ref:`get-started-setup-path`, while installing s/w
 Linux and MacOS
 ---------------
 
-Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
+Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file::
 
     export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:$IDF_PATH/tools"
 
-Log off and log in back to make this change effective. 
+Log off and log in back to make this change effective.
 
 .. note::
 
@@ -57,8 +56,15 @@ Run the following command to check if ``IDF_PATH`` is set::
 
 The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
 
-If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
+To verify idf.py is now on the ``PATH``, you can run the following::
+
+  which idf.py
+
+A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
+
+If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
 
     export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:$IDF_PATH/tools"
 
 If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
diff --git a/docs/en/get-started/eclipse-setup-windows.rst b/docs/en/get-started/eclipse-setup-windows.rst
deleted file mode 100644
index a924d2dc7..000000000
--- a/docs/en/get-started/eclipse-setup-windows.rst
+++ /dev/null
@@ -1,78 +0,0 @@
-**********************
-Eclipse IDE on Windows
-**********************
-
-Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.
-
-(For OS X and Linux instructions, see the :doc:`Eclipse IDE page <eclipse-setup>`.)
-
-Installing Eclipse IDE
-======================
-
-Follow the steps under :ref:`Installing Eclipse IDE <eclipse-install-steps>` for all platforms.
-
-.. _eclipse-windows-setup:
-
-Setting up Eclipse on Windows
-=============================
-
-Once your new Eclipse installation launches, follow these steps:
-
-Import New Project
-------------------
-
-* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
-
-* Once Eclipse is running, choose File -> Import...
-
-* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
-
-* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
-
-* On the same page, under "Toolchain for Indexer Settings" uncheck "Show only available toolchains that support this platform".
-
-* On the extended list that appears, choose "Cygwin GCC". Then click Finish.
-
-*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.*
-
-Project Properties
-------------------
-
-* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
-
-* Click on the "C/C++ Build" properties page (top-level):
-
-  * Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py``.
-
-* Click on the "Environment" properties page under "C/C++ Build":
-
-  * Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
-
-  * Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/MyUser/Development/esp-idf*.
-
-  * Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match).
-
-* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page:
-
-  * Click the "Providers" tab
-
-     * In the list of providers, click "CDT GCC Built-in Compiler Settings Cygwin". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
-
-     * In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern, and wrap remaining part with brackets. This means the full Compiler command pattern should be ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``
-
-
-Building in Eclipse
--------------------
-
-Continue from :ref:`Building in Eclipse <eclipse-build-project>` for all platforms.
-
-Technical Details
-=================
-
-**Of interest to Windows gurus or very curious parties, only.**
-
-Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support:
-
-* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility.
-
-* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse.
diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst
index 9ceb3c779..8b8c34c3b 100644
--- a/docs/en/get-started/eclipse-setup.rst
+++ b/docs/en/get-started/eclipse-setup.rst
@@ -2,108 +2,10 @@
 Build and Flash with Eclipse IDE
 ********************************
 
-.. _eclipse-install-steps:
-
-Installing Eclipse IDE
-======================
-
-The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
-
-* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
-
-* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
-
-* Download the Eclipse Installer for your platform from eclipse.org_.
-
-* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
-
-Windows Users
-=============
-
-Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
-
-Setting up Eclipse
-==================
-
-Once your new Eclipse installation launches, follow these steps:
-
-Import New Project
-------------------
-
-* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
-
-* Once Eclipse is running, choose File -> Import...
-
-* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
-
-* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
-
-* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
-
-
-Project Properties
-------------------
-
-* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
-
-* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
-
-* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed.
-
-* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path.
-
-* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
-
-Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
-
-* Click the "Providers" tab
-
-* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
-
-* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``
-
-.. _eclipse-build-project:
-
-Building in Eclipse
--------------------
-
-Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
-
-* Click OK to close the Properties dialog in Eclipse.
-
-* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
-
-*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
-
-* Back in Eclipse, choose Project -> Build to build your project.
-
-**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
-
-Flash from Eclipse
-------------------
-
-You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
-
-* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
-
-* Select Build Targets -> Create... from the context menu.
-
-* Type "flash" as the target name. Leave the other options as their defaults.
-
-* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
-
-Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
-
-Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
-
-Related Documents
------------------
-
-.. toctree::
-    :maxdepth: 1
-
-    eclipse-setup-windows
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
+Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
 
 .. _eclipse.org: https://www.eclipse.org/
 
diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
index c96c2e546..363de1cce 100644
--- a/docs/en/get-started/establish-serial-connection.rst
+++ b/docs/en/get-started/establish-serial-connection.rst
@@ -125,7 +125,4 @@ If you see some legible log, it means serial connection is working and you are r
 
 If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
 
-(If you are following the CMake preview documentation, `go back to the CMake-specific section instead <:ref:get-started-configure>`.
-
-
 .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
diff --git a/docs/en/get-started/idf-monitor.rst b/docs/en/get-started/idf-monitor.rst
index e1ec23cb3..30258de2f 100644
--- a/docs/en/get-started/idf-monitor.rst
+++ b/docs/en/get-started/idf-monitor.rst
@@ -2,7 +2,7 @@
 IDF Monitor
 ***********
 
-The idf_monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.
+The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
 
 It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific xfeatures.
 
@@ -66,7 +66,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an
 
 Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
 
-To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
+To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
 
 If this option is enabled and idf_monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
 
@@ -78,9 +78,9 @@ Behind the scenes, the command idf_monitor runs is::
 Quick Compile and Flash
 =======================
 
-The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``make flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
+The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
 
-The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``make app-flash`` target, then resume idf_monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed.
+The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
 
 
 Quick Reset
@@ -114,6 +114,7 @@ This program can still be run, via ``make simple_monitor``.
 
 idf_monitor is based on miniterm and shares the same basic keyboard shortcuts.
 
+.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
 
 Known Issues with idf_monitor
 =============================
diff --git a/docs/en/get-started/index-cmake.rst b/docs/en/get-started/index-cmake.rst
deleted file mode 100644
index 9bc7f0773..000000000
--- a/docs/en/get-started/index-cmake.rst
+++ /dev/null
@@ -1,347 +0,0 @@
-***************************************
-Get Started with the CMake build system
-***************************************
-
-.. note::
-   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). For a stable experience, follow the :doc:`original (non-cmake) setup guide here<index>`.
-
-This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32.
-
-Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
-
-
-Introduction
-============
-
-ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
-
-Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
-
-
-What You Need
-=============
-
-To develop applications for ESP32 you need:
-
-* **PC** loaded with either Windows, Linux or Mac operating system
-* **Toolchain** to build the **Application** for ESP32
-* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
-* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
-* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
-
-.. figure:: ../../_static/what-you-need.png
-    :align: center
-    :alt: Development of applications for ESP32
-    :figclass: align-center
-
-    Development of applications for ESP32
-
-Preparation of development environment consists of three steps:
-
-1. Setup of **Toolchain**
-2. Getting of **ESP-IDF** from GitHub
-3. Installation and configuration of **Eclipse**
-
-You may skip the last step, if you prefer to use different editor.
-
-Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
-
-1. Configuration of a **Project** and writing the code
-2. Compilation of the **Project** and linking it to build an **Application**
-3. Flashing (uploading) of the **Application** to **ESP32**
-4. Monitoring / debugging of the **Application**
-
-See instructions below that will walk you through these steps.
-
-
-Guides
-======
-
-If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
-
-.. toctree::
-    :maxdepth: 1
-
-    ESP32 DevKitC <get-started-devkitc>
-    ESP-WROVER-KIT <get-started-wrover-kit>
-    ESP32-PICO-KIT <get-started-pico-kit>
-
-If you have different board, move to sections below.
-
-
-.. _get-started-setup-toolchain-cmake:
-
-Setup Toolchain
-===============
-
-The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions. 
-
-.. toctree::
-    :hidden:
-
-    Windows <windows-setup-cmake>
-    Linux <linux-setup-cmake>
-    MacOS <macos-setup-cmake>
-
-+-------------------+-------------------+-------------------+
-| |windows-logo|    | |linux-logo|      | |macos-logo|      |
-+-------------------+-------------------+-------------------+
-| `Windows`_        | `Linux`_          | `Mac OS`_         |
-+-------------------+-------------------+-------------------+
-
-.. |windows-logo| image:: ../../_static/windows-logo.png
-    :target: ../get-started/windows-setup-cmake.html
-
-.. |linux-logo| image:: ../../_static/linux-logo.png
-    :target: ../get-started/linux-setup-cmake.html
-
-.. |macos-logo| image:: ../../_static/macos-logo.png
-    :target: ../get-started/macos-setup-cmake.html
-
-.. _Windows: ../get-started/windows-setup-cmake.html
-.. _Linux: ../get-started/linux-setup-cmake.html
-.. _Mac OS: ../get-started/macos-setup-cmake.html
-
-.. note::
-
-    We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
-
-Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
-
-Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`.
-
-
-.. _get-started-get-esp-idf-cmake:
-
-Get ESP-IDF
-===========
-
-.. highlight:: bash
-
-Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
-
-    cd ~/esp
-    git clone --recursive https://github.com/espressif/esp-idf.git
-
-ESP-IDF will be downloaded into ``~/esp/esp-idf``.
-
-.. note::
-
-    Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
-
-        cd ~/esp/esp-idf
-        git submodule update --init
-
-
-.. _get-started-setup-path-cmake:
-
-Setup Paths for ESP-IDF
-=======================
-
-The build system and tools find ESP-IDF using the ``IDF_PATH`` environment variable, or by running the ``idf.py`` utility in the tools/ directory of the esp-idf source.
-
-These paths should be set up as environment variables on your computer, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` and updating ``PATH`` in your user profile. To do so, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile-cmake`.
-
-.. _get-started-start-project-cmake:
-
-Start a Project
-===============
-
-Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
-
-Copy :example:`get-started/hello_world` to ``~/esp`` directory. You can do this via your operating system's file manager (like Windows Explorer). Or for Linux and MacOS, to do it from a Bash shell::
-
-    cd ~/esp
-    cp -r $IDF_PATH/examples/get-started/hello_world .
-
-
-You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
-
-.. important::
-
-    The esp-idf build system does not support spaces in paths to esp-idf or to projects.
-
-
-.. _get-started-connect-cmake:
-
-Connect
-=======
-
-You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
-
-
-.. _get-started-configure-cmake:
-
-Configure
-=========
-
-Open a terminal window (or a Windows Command Prompt), go to directory of the ``hello_world`` application by typing ``cd ~/esp/hello_world`` or ```cd \Users\esp\hello_world`` for Windows. Then start the project configuration utility ``menuconfig``::
-
-    cd ~/esp/hello_world
-    idf.py menuconfig
-
-.. note::
-   The first time you run ``idf.py`` for a given ESP-IDF project, CMake will run to configure the project. If any software tools or other requirements like environment variables are not configured correctly, this will produce a configuration error at this stage.
-
-.. note::
-    The previous (non-CMake) build system instructions would have told you to run ``make`` here, but the CMake-based system doesn't require use of ``make``.
-
-If previous steps have been done correctly, the following menu will be displayed:
-
-.. figure:: ../../_static/project-configuration.png
-    :align: center
-    :alt: Project configuration - Home window
-    :figclass: align-center
-
-    Project configuration - Home window
-
-In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
-
-.. note::
-
-   On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
-   (See :doc:`establish-serial-connection` for full details.)
-
-Here are couple of tips on navigation and use of ``menuconfig``:
-
-* Use up & down arrow keys to navigate the menu.
-* Use Enter key to go into a submenu, Escape key to go out or to exit.
-* Type ``?`` to see a help screen. Enter key exits the help screen.
-* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
-* Pressing ``?`` while highlighting a configuration item displays help about that item.
-* Type ``/`` to search the configuration items.
-
-.. _get-started-build-flash-cmake:
-
-Build and Flash
-===============
-
-Now you can build and flash the application. To build (but not flash) run::
-
-    idf.py build
-
-This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
-
-To flash these built firmware files to your ESP32 board, run::
-
-    idf.py -p <PORT> flash
-
-For ``<PORT>``, specify the connected ESP32's serial port like ``/dev/ttyUSB0`` (Linux), ``/dev/cu.USBx`` (MacOS) or ``COM1`` (Windows).
-
-.. highlight:: none
-
-::
-
-    esptool.py v2.0-beta2
-    Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
-    esptool.py v2.0-beta2
-    Connecting........___
-    Uploading stub...
-    Running stub...
-    Stub running...
-    Changing baud rate to 921600
-    Changed.
-    Attaching SPI flash...
-    Configuring flash size...
-    Auto-detected Flash size: 4MB
-    Flash params set to 0x0220
-    Compressed 11616 bytes to 6695...
-    Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
-    Hash of data verified.
-    Compressed 408096 bytes to 171625...
-    Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
-    Hash of data verified.
-    Compressed 3072 bytes to 82...
-    Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
-    Hash of data verified.
-
-    Leaving...
-    Hard resetting...
-
-If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
-
-.. note::
-   It's not necessary to run ``idf.py build`` before ``idf.py flash``, then flash step will automatically build the firmware if it needs to be built.
-
-.. _get-started-build-monitor-cmake:
-
-Monitor
-=======
-
-To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
-
-    $ idf.py monitor
-    --- idf_monitor on /dev/ttyUSB0 115200 ---
-    --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
-    ets Jun  8 2016 00:22:57
-
-    rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
-    ets Jun  8 2016 00:22:57
-    ...
-
-Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
-
-    ...
-    Hello world!
-    Restarting in 10 seconds...
-    I (211) cpu_start: Starting scheduler on APP CPU.
-    Restarting in 9 seconds...
-    Restarting in 8 seconds...
-    Restarting in 7 seconds...
-
-To exit the monitor use shortcut ``Ctrl+]``.
-
-.. note::
-
-    If instead of the messages above, you see a random garbage similar to::
-
-        e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
-        ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
-
-    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
-
-To execute ``idf.py flash`` and then ``idf.py monitor``, you can run ``idf.py flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
-
-.. note::
-   At the moment not all of the idf_monitor shortcuts work correctly with the CMake-based build system.
-
-That's all what you need to get started with ESP32!
-
-Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
-
-
-Updating ESP-IDF
-================
-
-After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
-
-Another solution is to update only what has changed. This method is useful if you have slow connection to the GiHub. To do the update run the following commands::
-
-    cd ~/esp/esp-idf
-    git pull
-    git submodule update --init --recursive
-
-The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
-
-If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
-
-    cd ~/esp
-    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
-    cd esp-idf-v2.1/
-    git checkout v2.1
-    git submodule update --init --recursive
-
-After that remember to :doc:`add-idf_path-to-profile-cmake`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
-
-
-Related Documents
-=================
-
-.. toctree::
-    :maxdepth: 1
-
-    add-idf_path-to-profile-cmake
-    establish-serial-connection
-    make-project
-    idf-monitor
-    toolchain-setup-scratch
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index dffffb929..b87a55076 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -2,7 +2,10 @@
 Get Started
 ***********
 
-This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. 
+This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+
+.. note::
+   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
 
 Introduction
@@ -99,13 +102,12 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
 
 .. note::
 
-    We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
+    We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and Mac OS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
 
 Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
 
 Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
 
-
 .. _get-started-get-esp-idf:
 
 Get ESP-IDF
@@ -115,26 +117,42 @@ Get ESP-IDF
 
 Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
 
+    mkdir -p ~/esp
     cd ~/esp
     git clone --recursive https://github.com/espressif/esp-idf.git
 
 ESP-IDF will be downloaded into ``~/esp/esp-idf``.
 
+.. highlight:: batch
+
+For Windows Command Prompt users, the equivalent commands are::
+
+    mkdir %userprofile%\esp
+    cd %userprofile%\esp
+    git clone --recursive https://github.com/espressif/esp-idf.git
+
+.. highlight:: bash
 .. note::
 
     Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
 
-        cd ~/esp/esp-idf
+        cd esp-idf
         git submodule update --init
 
 
 .. _get-started-setup-path:
 
-Setup Path to ESP-IDF
-=====================
+Setup Environment Variables
+===========================
 
-The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
+ESP-IDF requires two environment variables to be set for normal operation:
 
+- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
+- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
+
+These two variables should be set up on your PC, otherwise projects will not build.
+
+Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
 
 .. _get-started-start-project:
 
@@ -143,13 +161,24 @@ Start a Project
 
 Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
 
+.. highlight:: bash
+
 Copy :example:`get-started/hello_world` to ``~/esp`` directory::
 
     cd ~/esp
     cp -r $IDF_PATH/examples/get-started/hello_world .
 
+.. highlight:: batch
+
+For Windows Command Prompt users, the equivalent commands are::
+
+    cd %userprofile%\esp
+    xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
+
 You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
 
+It is also possible to build examples in-place, without copying them first.
+
 .. important::
 
     The esp-idf build system does not support spaces in paths to esp-idf or to projects.
@@ -168,12 +197,27 @@ You are almost there. To be able to proceed further, connect ESP32 board to PC,
 Configure
 =========
 
+.. highlight:: bash
+
 Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
 
     cd ~/esp/hello_world
-    make menuconfig
+    idf.py menuconfig
 
-If previous steps have been done correctly, the following menu will be displayed: 
+.. highlight:: batch
+
+For Windows Command Prompt users::
+
+    cd %userprofile%\esp
+    idf.py menuconfig
+
+.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`.
+
+.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work. You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
+
+.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
+
+If previous steps have been done correctly, the following menu will be displayed:
 
 .. figure:: ../../_static/project-configuration.png
     :align: center
@@ -182,13 +226,6 @@ If previous steps have been done correctly, the following menu will be displayed
 
     Project configuration - Home window
 
-In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
-
-.. note::
-
-   On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
-   (See :doc:`establish-serial-connection` for full details.)
-
 Here are couple of tips on navigation and use of ``menuconfig``:
 
 * Use up & down arrow keys to navigate the menu.
@@ -202,15 +239,18 @@ Here are couple of tips on navigation and use of ``menuconfig``:
 
     If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
 
-
 .. _get-started-build-flash:
 
 Build and Flash
 ===============
 
+.. highlight:: bash
+
 Now you can build and flash the application. Run::
 
-    make flash
+    idf.py -p PORT flash
+
+Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. (See :doc:`establish-serial-connection` for full details.)
 
 This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
 
@@ -218,35 +258,38 @@ This will compile the application and all the ESP-IDF components, generate bootl
 
 ::
 
-    esptool.py v2.0-beta2
-    Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
-    esptool.py v2.0-beta2
-    Connecting........___
-    Uploading stub...
-    Running stub...
-    Stub running...
-    Changing baud rate to 921600
-    Changed.
-    Attaching SPI flash...
-    Configuring flash size...
-    Auto-detected Flash size: 4MB
-    Flash params set to 0x0220
-    Compressed 11616 bytes to 6695...
-    Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
-    Hash of data verified.
-    Compressed 408096 bytes to 171625...
-    Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
-    Hash of data verified.
-    Compressed 3072 bytes to 82...
-    Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
-    Hash of data verified.
+   Running esptool.py in directory [...]/esp/hello_world
+   Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
+   esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
+   esptool.py v2.3.1
+   Connecting....
+   Detecting chip type... ESP32
+   Chip is ESP32D0WDQ6 (revision 1)
+   Features: WiFi, BT, Dual Core
+   Uploading stub...
+   Running stub...
+   Stub running...
+   Changing baud rate to 460800
+   Changed.
+   Configuring flash size...
+   Auto-detected Flash size: 4MB
+   Flash params set to 0x0220
+   Compressed 22992 bytes to 13019...
+   Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
+   Hash of data verified.
+   Compressed 3072 bytes to 82...
+   Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
+   Hash of data verified.
+   Compressed 136672 bytes to 67544...
+   Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
+   Hash of data verified.
 
-    Leaving...
-    Hard resetting...
+   Leaving...
+   Hard resetting via RTS pin...
 
-If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
+If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.
 
-If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
+If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
 
 
 .. _get-started-build-monitor:
@@ -254,10 +297,11 @@ If you'd like to use the Eclipse IDE instead of running ``make``, check out the
 Monitor
 =======
 
-To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
+To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
 
-    $ make monitor
-    MONITOR
+    $ idf.py monitor
+    Running idf_monitor in directory [...]/esp/hello_world/build
+    Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
     --- idf_monitor on /dev/ttyUSB0 115200 ---
     --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
     ets Jun  8 2016 00:22:57
@@ -276,7 +320,7 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo
     Restarting in 8 seconds...
     Restarting in 7 seconds...
 
-To exit the monitor use shortcut ``Ctrl+]``. 
+To exit the monitor use shortcut ``Ctrl+]``.
 
 .. note::
 
@@ -285,11 +329,19 @@ To exit the monitor use shortcut ``Ctrl+]``.
         e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
         ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
 
-    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
 
-To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
+.. note::
 
-That's all what you need to get started with ESP32! 
+   You can combine building, flashing and monitoring into one step as follows::
+
+       idf.py -p PORT flash monitor
+
+Check the section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
+
+Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
+
+That's all what you need to get started with ESP32!
 
 Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
 
@@ -299,14 +351,26 @@ Updating ESP-IDF
 
 After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
 
+.. highlight:: bash
+
 Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands::
 
     cd ~/esp/esp-idf
     git pull
     git submodule update --init --recursive
 
+.. highlight:: batch
+
+For Windows Command Prompt users::
+
+    cd %userprofile%\esp
+    git pull
+    git submodule update --init --recursive
+
 The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
 
+.. highlight:: bash
+
 If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
 
     cd ~/esp
@@ -315,8 +379,22 @@ If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
     git checkout v2.1
     git submodule update --init --recursive
 
+.. highlight:: batch
+
+For Windows Command Prompt users::
+
+    cd %userprofile%\esp
+    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
+    cd esp-idf-v2.1/
+    git checkout v2.1
+    git submodule update --init --recursive
+
 After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
 
+.. note::
+
+   Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
+
 
 Related Documents
 =================
diff --git a/docs/en/get-started/linux-setup-cmake.rst b/docs/en/get-started/linux-setup-cmake.rst
deleted file mode 100644
index 2e3bbdbbe..000000000
--- a/docs/en/get-started/linux-setup-cmake.rst
+++ /dev/null
@@ -1,113 +0,0 @@
-*************************************
-Setup for cmake on Linux
-*************************************
-
-.. note::
-   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<linux-setup>`.
-
-Install Prerequisites
-=====================
-
-To compile with ESP-IDF you need to get the following packages:
-
-- CentOS 7::
-
-    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
-
-- Ubuntu and Debian::
-
-    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
-
-- Arch::
-
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
-
-.. note::
-    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
-
-Toolchain Setup
-===============
-
-ESP32 toolchain for Linux is available for download from Espressif website:
-
-- for 64-bit Linux:
-
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
-
-- for 32-bit Linux:
-
-  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
-
-1.  Download this file, then extract it in ``~/esp`` directory::
-
-        mkdir -p ~/esp
-        cd ~/esp
-        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
-
-.. _setup-linux-toolchain-add-it-to-path:
-
-2.  The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
-
-    To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
-
-        export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
-
-    Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
-
-        alias get_esp32='export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
-
-    Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
-
-    .. note::
-
-        If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
-
-3.  Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
-
-        printenv PATH
-
-    You are looking for similar result containing toolchain's path at the end of displayed string::
-
-        $ printenv PATH
-        /home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
-
-    Instead of ``/home/user-name`` there should be a home path specific to your installation.
-
-
-Permission issues /dev/ttyUSB0
-------------------------------
-
-With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
-
-
-Arch Linux Users
-----------------
-
-To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. 
-
-Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
-
-- https://aur.archlinux.org/packages/ncurses5-compat-libs/
-- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
-
-Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
-
-Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
-
-
-Next Steps
-==========
-
-To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
-
-
-Related Documents
-=================
-
-.. toctree::
-    :maxdepth: 1
-
-    linux-setup-scratch
-
-
-.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst
index b2cb96ec3..1c1d287e8 100644
--- a/docs/en/get-started/linux-setup-scratch.rst
+++ b/docs/en/get-started/linux-setup-scratch.rst
@@ -2,6 +2,9 @@
 Setup Linux Toolchain from Scratch
 **********************************
 
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+
 The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
 
 
@@ -10,14 +13,20 @@ Install Prerequisites
 
 To compile with ESP-IDF you need to get the following packages:
 
+- CentOS 7::
+
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
+
 - Ubuntu and Debian::
 
-    sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
 
+.. note::
+    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
 
 Compile the Toolchain from Source
 =================================
@@ -26,19 +35,19 @@ Compile the Toolchain from Source
 
   - CentOS 7::
 
-        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
+        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
 
   - Ubuntu pre-16.04::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
 
   - Ubuntu 16.04::
 
-        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
+        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
 
   - Debian 9::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
 
   - Arch::
 
diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst
index 8004c37ee..3736191bc 100644
--- a/docs/en/get-started/linux-setup.rst
+++ b/docs/en/get-started/linux-setup.rst
@@ -2,6 +2,8 @@
 Standard Setup of Toolchain for Linux
 *************************************
 
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
 Install Prerequisites
 =====================
@@ -10,16 +12,18 @@ To compile with ESP-IDF you need to get the following packages:
 
 - CentOS 7::
 
-    sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
 
 - Ubuntu and Debian::
 
-    sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-serial
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
 
+.. note::
+    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
 
 Toolchain Setup
 ===============
@@ -79,7 +83,7 @@ With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0
 Arch Linux Users
 ----------------
 
-To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. 
+To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
 
 Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
 
diff --git a/docs/en/get-started/macos-setup-cmake.rst b/docs/en/get-started/macos-setup-cmake.rst
deleted file mode 100644
index ce5623a53..000000000
--- a/docs/en/get-started/macos-setup-cmake.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-*************************
-Setup for CMake on Mac OS
-*************************
-
-.. note::
-      The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is `here <:doc:macos-setup>`.
-
-Install Prerequisites
-=====================
-
-- install pip::
-
-    sudo easy_install pip
-
-- install pyserial::
-
-    sudo pip install pyserial
-
-- install CMake & Ninja build:
-
-  If you have HomeBrew, you can run::
-
-    brew install cmake ninja
-
-  Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation.
-
-- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew, this can be done via ``brew install ccache``.
-
-Toolchain Setup
-===============
-
-ESP32 toolchain for macOS is available for download from Espressif website:
-
-https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
-
-Download this file, then extract it in ``~/esp`` directory::
-
-    mkdir -p ~/esp
-    cd ~/esp
-    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
-
-.. _setup-macos-toolchain-add-it-to-path:
-
-The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
-
-To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
-
-    export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin
-
-Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
-
-    alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
-
-Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
-
-
-Next Steps
-==========
-
-To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
-
-.. _cmake: https://cmake.org/
-.. _ninja: https://ninja-build.org/
-.. _ccache: https://ccache.samba.org/
diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst
index 7516158a1..53b8a9947 100644
--- a/docs/en/get-started/macos-setup-scratch.rst
+++ b/docs/en/get-started/macos-setup-scratch.rst
@@ -2,6 +2,16 @@
 Setup Toolchain for Mac OS from Scratch
 ***************************************
 
+Package Manager
+===============
+
+To set up the toolchain from scratch, rather than `downloading a precocmpiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or homebrew_ package manager.
+
+MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
+
+    .. _homebrew: https://brew.sh/
+    .. _MacPorts: https://www.macports.org/install.php
+
 Install Prerequisites
 =====================
 
@@ -13,24 +23,28 @@ Install Prerequisites
 
     sudo pip install pyserial
 
+- install CMake & Ninja build:
+
+  - If you have HomeBrew, you can run::
+
+      brew install cmake ninja
+
+  - If you have MacPorts, you can run::
+
+      sudo port install cmake ninja
 
 Compile the Toolchain from Source
 =================================
 
 - Install dependencies:
 
-  - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
-    
-    .. _homebrew: https://brew.sh/
-    .. _MacPorts: https://www.macports.org/install.php
-
   - with MacPorts::
 
-        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
+        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
 
   - with homebrew::
 
-        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
+        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
 
 Create a case-sensitive filesystem image::
 
diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst
index 14764601b..a699c3bef 100644
--- a/docs/en/get-started/macos-setup.rst
+++ b/docs/en/get-started/macos-setup.rst
@@ -2,6 +2,9 @@
 Standard Setup of Toolchain for Mac OS
 **************************************
 
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+
 Install Prerequisites
 =====================
 
@@ -13,6 +16,19 @@ Install Prerequisites
 
     sudo pip install pyserial
 
+- install CMake & Ninja build:
+
+  - If you have HomeBrew_, you can run::
+
+      brew install cmake ninja
+
+  - If you have MacPorts_, you can run::
+
+      sudo port install cmake ninja
+
+  - Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation downloads.
+
+- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
 
 Toolchain Setup
 ===============
@@ -47,7 +63,6 @@ Next Steps
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
-
 Related Documents
 =================
 
@@ -55,3 +70,9 @@ Related Documents
     :maxdepth: 1
 
     macos-setup-scratch
+
+.. _cmake: https://cmake.org/
+.. _ninja: https://ninja-build.org/
+.. _ccache: https://ccache.samba.org/
+.. _homebrew: https://brew.sh/
+.. _MacPorts: https://www.macports.org/install.php
diff --git a/docs/en/get-started/windows-setup-cmake.rst b/docs/en/get-started/windows-setup-cmake.rst
deleted file mode 100644
index 0545e7d50..000000000
--- a/docs/en/get-started/windows-setup-cmake.rst
+++ /dev/null
@@ -1,58 +0,0 @@
-***************************************
-Setup for cmake on Windows
-***************************************
-
-.. note::
-      The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). The original (non-cmake) version of this doc is :doc:`here<windows-setup>`.
-
-.. note::
-      The CMake-based build system is only supported on 64-bit versions of Windows.
-
-Introduction
-============
-
-Unlike the conventional ESP-IDF make-based build environment, cmake does not require MSYS2 or another GNU-compatible environment (like Cygwin) for building. You can build with cmake from Windows Command Prompt, or from an IDE with cmake support.
-
-ESP-IDF Tools Installer
-=======================
-
-The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
-
-https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe
-
-The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and mconf configuration tool. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
-
-By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
-
-Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
-
-Installing Git
-==============
-
-The ESP-IDF tools does not include Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a Git command line for Windows (along with the Git-Bash terminal) from https://gitforwindows.org/.
-
-If you prefer to use a different graphical Git client, then you can install one of these instead - you will need to translate the Git commands in the getting started guide for use with your chosen Git client.
-
-
-Related Documents
-=================
-
-.. toctree::
-    :maxdepth: 1
-
-    windows-setup-scratch-cmake
-
-Manual Installation
-^^^^^^^^^^^^^^^^^^^
-
-Optionall
-
-Next Steps
-==========
-
-To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
-
-
-.. _cmake: https://cmake.org/download/
-.. _ninja: https://ninja-build.org/
-.. _Python: https://www.python.org/downloads/windows/
diff --git a/docs/en/get-started/windows-setup-scratch-cmake.rst b/docs/en/get-started/windows-setup-scratch-cmake.rst
deleted file mode 100644
index a4e12ae5c..000000000
--- a/docs/en/get-started/windows-setup-scratch-cmake.rst
+++ /dev/null
@@ -1,85 +0,0 @@
-***************************************
-Setup for cmake on Windows from Scratch
-***************************************
-
-Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`ESP-IDF Tools Installer <windows-setup-cmake>` automates the steps mentioned below.
-
-To quickly setup the toolchain and other tools in standard way, using the installer, proceed to section :doc:`windows-setup-cmake`.
-
-Note that, unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer.
-
-Tools
-=====
-
-cmake
-^^^^^
-
-Download the latest stable release of CMake_ for Windows and run the installer.
-
-When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
-
-Ninja build
-^^^^^^^^^^^
-
-.. note::
-    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
-
-Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
-
-The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>` (or you can choose a directory which is already on your Path).
-
-
-Python 2.x
-^^^^^^^^^^
-
-Download the latest Python_ 2.7 for Windows installer, and run it.
-
-The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
-
-Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
-
-  pip install pyserial
-
-MConf
-^^^^^
-
-Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page <mconf>`.
-
-This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`.
-
-Toolchain Setup
-===============
-
-Download the precompiled Windows toolchain from dl.espressif.com:
-
-https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
-
-Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
-
-Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
-
-.. note::
-   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
-
-
-.. _add-directory-windows-path:
-
-Adding Directory to Path
-========================
-
-To add any new directory to your Windows Path environment variable:
-
-Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
-
-Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
-
-Next Steps
-==========
-
-To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
-
-
-.. _cmake: https://cmake.org/download/
-.. _ninja: https://ninja-build.org/
-.. _ninja-dl: https://github.com/ninja-build/ninja/releases
-.. _Python: https://www.python.org/downloads/windows/
diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst
index 4c772eeb3..908897613 100644
--- a/docs/en/get-started/windows-setup-scratch.rst
+++ b/docs/en/get-started/windows-setup-scratch.rst
@@ -2,91 +2,81 @@
 Setup Windows Toolchain from Scratch
 ************************************
 
-Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps. 
+This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
 
-To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
+To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
 
-
-.. _configure-windows-toolchain-from-scratch:
-
-Configure Toolchain & Environment from Scratch
-==============================================
-
-This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
-
-* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
-
-* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
-
-* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
-
-  *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
-
-* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
-
-* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
-
-* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
-
-
-Troubleshooting
-~~~~~~~~~~~~~~~
-
-* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
-
-     *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
-
-  If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
-
-* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
-
-
-MSYS2 Mirrors in China
-~~~~~~~~~~~~~~~~~~~~~~
-
-There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
-
-To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
-
-Add these lines at the top of ``mirrorlist.mingw32``::
-
-  Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
-  Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
-
-Add these lines at the top of ``mirrorlist.msys``::
-
-  Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
-  Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
-
-
-HTTP Proxy
-~~~~~~~~~~
-
-You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
-
-    export http_proxy='http://http.proxy.server:PORT'
-
-Or with credentials::
-
-    export http_proxy='http://user:password@http.proxy.server:PORT'
-
-Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
-
-
-Alternative Setup: Just download a toolchain
-============================================
-
-If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
-
-https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
 .. note::
 
-	If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
+    Unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer.
 
-.. important::
+Tools
+=====
 
-	Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
+cmake
+^^^^^
+
+Download the latest stable release of CMake_ for Windows and run the installer.
+
+When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
+
+Ninja build
+^^^^^^^^^^^
+
+.. note::
+    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
+
+Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
+
+The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_ (or you can choose a directory which is already on your Path).
+
+
+Python 2.x
+^^^^^^^^^^
+
+Download the latest Python_ 2.7 for Windows installer, and run it.
+
+The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
+
+Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
+
+  pip install pyserial
+
+MConf
+^^^^^
+
+Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page <mconf>`_.
+
+This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
+
+Toolchain Setup
+===============
+
+Download the precompiled Windows toolchain from dl.espressif.com:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+
+Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
+
+Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
+
+.. note::
+   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
+
+
+.. _add-directory-windows-path:
+
+Adding Directory to Path
+========================
+
+To add any new directory to your Windows Path environment variable:
+
+Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
+
+Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
 
 
 Next Steps
@@ -94,22 +84,5 @@ Next Steps
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
-.. _updating-existing-windows-environment:
-
-Updating The Environment
-========================
-
-When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
-
-Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
-
-- Update IDF to the new version you want to use.
-- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
-
-The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
-
-If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
-
-.. _MSYS2: https://msys2.github.io/
-.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
-.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new
+.. _ninja: https://ninja-build.org/
+.. _Python: https://www.python.org/downloads/windows/
diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst
index e2adebde2..c9e1b7011 100644
--- a/docs/en/get-started/windows-setup.rst
+++ b/docs/en/get-started/windows-setup.rst
@@ -2,64 +2,61 @@
 Standard Setup of Toolchain for Windows
 ***************************************
 
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+
+.. note::
+      The CMake-based build system is only supported on 64-bit versions of Windows.
+
 Introduction
 ============
 
-Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
+ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
 
+For this Getting Started we're going to use a command prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
 
-Toolchain Setup 
-===============
+.. note::
+   Previous versions of ESP-IDF used a GNU Make based build system, which required the MSYS2_ Unix compatibility environment on Windows. This is no longer required.
 
-The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
+ESP-IDF Tools Installer
+=======================
 
-https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip
+The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
 
-Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
+https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe
 
+The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a customized configuration tool called mconf. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
 
-Check it Out
-============
+By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
 
-Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
+Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
 
-    mkdir -p ~/esp
+Installing Git
+==============
 
-By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step.
+The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
 
-.. figure:: ../../_static/msys2-terminal-window.png
-    :align: center
-    :alt: MSYS2 MINGW32 shell window
-    :figclass: align-center
+If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
 
-    MSYS2 MINGW32 shell window
+Using a Terminal
+================
 
-Use this window in the following steps setting up development environment for ESP32.
+For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
 
+- You can use the built-in Windows Command Prompt, under the Start menu. Note that command line instructions in this documentation give "bash" commands for Mac OS or Linux first. The Windows Command Prompt equivalent is given afterwards.
+- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as Mac OS or Linux. You can find it in the Start menu once installed.
+- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
 
 Next Steps
 ==========
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
-Updating The Environment
-========================
-
-When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
-
-- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
-- Download the new precompiled environment using the steps above.
-- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
-- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
-- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
-
-You can have independent different MSYS2 environments on your system, as long as they are in different directories.
-
-There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
-
 Related Documents
 =================
 
+For advanced users who want to customize the install process:
+
 .. toctree::
     :maxdepth: 1
 
@@ -67,3 +64,9 @@ Related Documents
 
 
 .. _MSYS2: https://msys2.github.io/
+.. _cmake: https://cmake.org/download/
+.. _ninja: https://ninja-build.org/
+.. _Python: https://www.python.org/downloads/windows/
+.. _Git for Windows: https://gitforwindows.org/
+.. _mconf: https://github.com/espressif/kconfig-frontends/releases/
+.. _Github Desktop: https://desktop.github.com/
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 317eff85d..a92218f32 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -3,6 +3,9 @@ ESP-IDF Programming Guide
 
 This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
 
+.. note::
+   This is documentation for the the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+
 ==================  ==================  ==================
 |Get Started|_      |API Reference|_    |H/W Reference|_
 ------------------  ------------------  ------------------
@@ -40,7 +43,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
    API Reference <api-reference/index>
    H/W Reference <hw-reference/index>
    API Guides <api-guides/index>
-   CMake Build System Preview <api-guides/cmake-preview-index>
    Contribute <contribute/index>
    Resources <resources>
    Copyrights <COPYRIGHT>
diff --git a/docs/zh_CN/api-guides/gnu-make-build-system.rst b/docs/zh_CN/api-guides/gnu-make-build-system.rst
new file mode 100644
index 000000000..19bc45fc3
--- /dev/null
+++ b/docs/zh_CN/api-guides/gnu-make-build-system.rst
@@ -0,0 +1 @@
+.. include:: ../../en/api-guides/gnu-make-build-system.rst
diff --git a/docs/zh_CN/get-started/eclipse-setup-windows.rst b/docs/zh_CN/get-started/eclipse-setup-windows.rst
deleted file mode 100644
index ba15bc9db..000000000
--- a/docs/zh_CN/get-started/eclipse-setup-windows.rst
+++ /dev/null
@@ -1,81 +0,0 @@
-*****************************************************
-Eclipse IDE 的创建和烧录指南（Windows 平台）
-*****************************************************
-
-Windows 平台上的 Eclipse 配置略有不同，具体步骤请见下文。
-
-注意：OS X 和 Linux 平台上的 Eclipse IDE 配置，请见 :doc:`Eclipse IDE page <eclipse-setup>`。
-
-安装 Eclipse IDE
-==================
-
-Windows 平台的 Eclipse 安装步骤与其他平台相同，请见 :ref:`Installing Eclipse IDE <eclipse-install-steps>`。
-
-.. _eclipse-windows-setup:
-
-
-Windows 平台上的 Eclipse 配置
-================================
-
-完成 Eclipse IDE 的安装后，请按照下列步骤继续操作：
-
-导入新项目
--------------
-
-* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
-
-* 运行 Eclipse，选择 “File” -> “Import...”。
-
-* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
-
-* 下个界面，在 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应填入 ESP-IDF 项目的路径，而非 ESP-IDF 的路径（稍后再填写）。此外，您指定的目录中应包含名为 “Makefile”（项目 Makefile）的文件。
-
-* 在同一页面上，在 “Toolchain for Indexer Settings” 下取消选中 “Show only available toolchains that support this platform”。
-
-* 在出现的扩展列表中，选择 “Cygwin GCC”。然后点击 “Finish”。
-
-*注意：您可能看到有关“无法找到 Cygwin GCC 工具链”的警告。这种情况并不影响安装，我们只需重新配置 Eclipse，并找到我们的工具链即可。*
-
-项目属性 
-----------
-
-* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择顶层 “Properties”。
-
-* 点击 “C/C++ Build” 属性页。
-
-	* 取消选中 “Use default build command”，然后输入命令：``python${IDF_PATH}/tools/windows/eclipse_make.py``，开始自定义创建。
-
-* 点击 “C/C++ Build” 下的 “Environment” 属性页面。
-
-	* 选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
-
-	* 再次点击 “Add...”，输入名称 ``IDF_PATH``，并填写 ESP-IDF 的完整安装路径。``IDF_PATH`` 目录路径应使用正斜杠，而非反斜线，即 ``C:/Users/MyUser/Development/esp-idf``。
-
-	* 选择 PATH 环境变量，删除默认值，并将其替换为 ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` （如果您已经将 msys32 安装到其他目​​录，这里请自行调整）。
-
-
-* 点击 “C/C++ General” -> “Preprocessor Include Paths, Macros, etc.” 属性页。
-
-	* 点击 “Providers” 选项卡。
-
-		* 从 “Providers” 列表中选择 “CDT GCC Built-in Compiler Settings Cygwin”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终完整的 ``Command to get compiler specs`` 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
-		
-		* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``，并用括号把剩余部分扩起来。最终的完整 Compiler 命令模式应为 ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``。
-
-
-在 Eclipse IDE 中创建项目
----------------------------
-
-Windows 平台的 Eclipse 项目创建步骤与其他平台相同，请见 :ref:`Building in Eclipse <eclipse-build-project>`。
-
-技术细节
-=========
-
-**以下内容仅供 Windows 平台专家或非常感兴趣的开发者阅读。**
-
-Windows 平台的 Eclipse 介绍到此结束，下方将主要将介绍一些关键步骤的原理，助您了解更多 Eclipse 的背景信息。
-
-* 首先，xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链，但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于：msys2 需要使用 Cygwin，并支持 Unix 风格的路径，即 ``/c/blah``，而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是，``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能，其内置 “include” 目录全部位于 ``/usr/`` 路径下，这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 风格路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器，可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。
-
-
-* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 Eclipse 的结果。
\ No newline at end of file
diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst
index 8db863942..634c5ee12 100644
--- a/docs/zh_CN/get-started/eclipse-setup.rst
+++ b/docs/zh_CN/get-started/eclipse-setup.rst
@@ -2,107 +2,6 @@
 Eclipse IDE 的创建和烧录指南
 ****************************
 
-.. _eclipse-install-steps:
-
-安装 Eclipse IDE
-================
-
-Eclipse IDE 是一个可视化的集成开发环境，可用于编写、编译和调试 ESP-IDF 项目。
-
-* 首先，请在您的平台上安装相应的 ESP-IDF，具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。
-
-* 我们建议，您应首先使用命令行创建一个项目，大致熟悉项目的创建流程。此外，您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前，Eclipse 尚不支持对 ESP-IDF 项目进行配置。
-
-* 下载相应版本的 Eclipse Installer 至您的平台，点击 eclipse.org_。
-
-* 运行 Eclipse Installer，选择 “Eclipse for C/C++ Development”（有的版本也可能显示为 CDT）。
-
-Windows 用户
-============
-
-在 Windows 平台上使用 Eclipse IDE 的用户，请参考 :ref:`Windows 用户的 Eclipse IDE 使用指南 <eclipse-windows-setup>`。
-
-配置 Eclipse IDE
-=================
-
-请打开安装好的 Eclipse IDE，并按照以下步骤进行操作：
-
-导入新项目
-----------
-
-* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
-
-* 运行 Eclipse，选择 “File” -> “Import...”。
-
-* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
-
-* 在下个界面中 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应输入 ESP-IDF 项目的路径，而非 ESP-IDF 本身的路径（这个稍后再填）。此外，您指定的目标路径中应包含名为 ``Makefile`` （项目 Makefile）的文件。
-
-* 在本界面，找到 “Toolchain for Indexer Settings”，选择 “Cross GCC”，最后点击 “Finish”。
-
-
-项目属性
---------
-
-* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择 “Properties”。
-
-* 点击 “C/C++ Build” 下的 “Environment” 属性页，选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
-
-* 再次点击 “Add...”，并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。
-
-* 选择 “PATH” 环境变量，不要改变默认值。如果 Xtensa 工具链的路径尚不在 “PATH” 列表中，则应将该路径 (``something/xtensa-esp32-elf/bin``) 增加至列表。
-
-* 在 macOS 平台上，增加一个 “PYTHONPATH” 环境变量，并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``， 保证系统中预先安装的 Python （需安装 pyserial 模块）可以覆盖 Eclipse 内置的任何 Python。
-
-* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。
-
-	* 点击 “Providers” 选项卡。从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终的完整 “Command to get compiler specs” 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
-
-	* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 “Compiler command pattern“ 输入框的起始位置输入 ``xtensa-esp32-elf-``，最终的完整编译器命令应为 ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``。
-
-.. _eclipse-build-project:
-
-在 Eclipse IDE 中创建项目
---------------------------
-
-在首次创建项目前，Eclipse IDE 可能会显示大量有关未定义值的错误和警告，主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目创建过程中自动生成的。因此，这些错误和警告将在 ESP-IDF 项目生成完成后消失。
-
-* 点击 “OK”，关闭 Eclipse IDE 中的 “Properties” 对话框。
-
-* 在 Eclipse IDE 界面外，打开命令管理器。进入项目目录，并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段，您还无法在 Eclipse 中完成本操作。
-
-*如果您未进行最开始的配置步骤，ESP-IDF 将提示在命令行中进行配置 - 但由于 Eclipse 暂时不支持相关功能，因此该项目将挂起或创建失败。*
-
-* 返回 Eclipse IDE 界面中，选择 “Project” -> “Build” 创建您的项目。
-
-**提示**：如果您已经在 Eclipse IDE 环境外创建了项目，则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”，允许 Eclipse 查看所有源文件的编译器参数，并借此确定头文件包含路径。
-
-在 Eclipse IDE 中烧录项目
---------------------------
-
-您可以将 ``make flash`` 目标放在 Eclipse 项目中，通过 Eclipse UI 调用 ``esptool.py`` 进行烧录：
-
-* 打开 “Project Explorer”，并右击您的项目（请注意右击项目本身，而非项目下的子文件，否则 Eclipse 可能会找到错误的 ``Makefile``）。
-
-* 从菜单中选择 “Make Targets” -> “Create”。
-
-* 输入 “flash” 为目标名称，其他选项使用默认值。
-
-* 选择 “Project” -> “Make Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。
-
-注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。
-
-如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。
-
-相关文档
---------
-
-.. toctree::
-    :maxdepth: 1
-
-    eclipse-setup-windows
-
-
-.. _eclipse.org: https://www.eclipse.org/
+.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
 
 
diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst
index e2eb3d2ea..be92cc0d6 100644
--- a/docs/zh_CN/get-started/index.rst
+++ b/docs/zh_CN/get-started/index.rst
@@ -2,6 +2,8 @@
 快速入门
 ***********
 
+.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
+
 本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework)，包括配置、编译、下载固件到开发板等步骤。
 
 概述
diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst
index a4dc1d943..267782a37 100644
--- a/docs/zh_CN/get-started/linux-setup.rst
+++ b/docs/zh_CN/get-started/linux-setup.rst
@@ -2,6 +2,8 @@
 Linux 平台工具链的标准设置
 *****************************
 
+.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
+
 安装前提
 =====================
 
diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst
index ea5b6c60d..b7c303f13 100644
--- a/docs/zh_CN/get-started/macos-setup.rst
+++ b/docs/zh_CN/get-started/macos-setup.rst
@@ -2,6 +2,8 @@
 在 Mac OS 上安装 ESP32 工具链
 **************************************
 
+.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
+
 安装准备
 ================
 
diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst
index d83408e3c..bff59ab99 100644
--- a/docs/zh_CN/get-started/windows-setup.rst
+++ b/docs/zh_CN/get-started/windows-setup.rst
@@ -2,6 +2,8 @@
 Windows 平台工具链的标准设置
 ***************************************
 
+.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
+
 引言
 ============
 
@@ -53,8 +55,6 @@ https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110
 
 你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。
 
-或者，:ref:`你也可以更新现有的环境而不是下载新环境 <updating-existing-windows-environment>`，但是这样更复杂。
-
 相关文档
 =================
 
diff --git a/tools/idf.py b/tools/idf.py
index 989f31063..3607a9003 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -322,12 +322,12 @@ ACTIONS = {
     "size-files":            ( build_target, [ "app" ], [] ),
     "bootloader":            ( build_target, [], [] ),
     "bootloader-clean":      ( build_target, [], [] ),
-    "bootloader-flash":      ( flash,        [ "bootloader" ], [] ),
+    "bootloader-flash":      ( flash,        [ "bootloader" ], [ "erase_flash"] ),
     "app":                   ( build_target, [], [ "clean", "fullclean", "reconfigure" ] ),
-    "app-flash":             ( flash,        [ "app" ], []),
+    "app-flash":             ( flash,        [ "app" ], [ "erase_flash"]),
     "partition_table":       ( build_target, [], [ "reconfigure" ] ),
-    "partition_table-flash": ( flash,        [ "partition_table" ], []),
-    "flash":                 ( flash,        [ "all" ], [ ] ),
+    "partition_table-flash": ( flash,        [ "partition_table" ], [ "erase_flash" ]),
+    "flash":                 ( flash,        [ "all" ], [ "erase_flash" ] ),
     "erase_flash":           ( erase_flash,  [], []),
     "monitor":               ( monitor,      [], [ "flash", "partition_table-flash", "bootloader-flash", "app-flash" ]),
 }
diff --git a/tools/unit-test-app/README.md b/tools/unit-test-app/README.md
index 1f06be55b..2df5e8251 100644
--- a/tools/unit-test-app/README.md
+++ b/tools/unit-test-app/README.md
@@ -7,7 +7,7 @@ ESP-IDF unit tests are run using Unit Test App. The app can be built with the un
 * Follow the setup instructions in the top-level esp-idf README.
 * Set IDF_PATH environment variable to point to the path to the esp-idf top-level directory.
 * Change into `tools/unit-test-app` directory
-* `make menuconfig` to configure the Unit Test App.
+* `idf.py menuconfig` to configure the Unit Test App.
 * `make TEST_COMPONENTS=` with `TEST_COMPONENTS` set to names of the components to be included in the test app. Or `make TESTS_ALL=1` to build the test app with all the tests for components having `test` subdirectory.
 * Follow the printed instructions to flash, or run `make flash`.
 

From b7ddb0c3d3664df269d0c27126650dfffce51238 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 7 May 2018 09:11:39 +0800
Subject: [PATCH 059/112] Revert "docs: Temporarily allow cmake docs to be in
 English only"

This reverts commit d5a58971402a5bebe126a809544304b2f385f36d.
---
 docs/check_lang_folder_sync.sh | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/check_lang_folder_sync.sh b/docs/check_lang_folder_sync.sh
index 5840bea2a..96de9994c 100755
--- a/docs/check_lang_folder_sync.sh
+++ b/docs/check_lang_folder_sync.sh
@@ -20,8 +20,7 @@ find zh_CN -type f | cut -d/ -f2- | sort > file_list_zh_CN
 # format is to display new or different filenames
 DIFF_FORMAT="--unchanged-line-format= --old-line-format=[en]:%L --new-line-format=[zh_CN]:%L"
 
-# TEMPORARY MODIFICATION: -cmake docs are English-only for now
-FOLDER_DIFFERENCES=$(diff $DIFF_FORMAT file_list_en file_list_zh_CN | grep -v "cmake")
+FOLDER_DIFFERENCES=$(diff $DIFF_FORMAT file_list_en file_list_zh_CN)
 if ! [ -z "$FOLDER_DIFFERENCES" ]; then
     echo "$STARS"
     echo "Build failed due to the following differences in 'en' and 'zh_CN' folders:"

From 6f31674b28ae130d96bc1b882870d61c585dc021 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 7 May 2018 09:31:37 +0800
Subject: [PATCH 060/112] cmake: Add ESPORT/ESPBAUD environment variables to
 idf.py & docs

---
 docs/en/api-guides/build-system.rst          | 2 ++
 docs/en/api-guides/gnu-make-build-system.rst | 4 ++++
 tools/idf.py                                 | 6 ++++--
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index 28789b307..2135ca0a2 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -88,6 +88,8 @@ Type ``idf.py --help`` for a full list of commands. Here are a summary of the mo
 
 Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
 
+.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
+
 Advanced Commands
 ^^^^^^^^^^^^^^^^^
 
diff --git a/docs/en/api-guides/gnu-make-build-system.rst b/docs/en/api-guides/gnu-make-build-system.rst
index 1f9c5b9bd..d1a8a41f9 100644
--- a/docs/en/api-guides/gnu-make-build-system.rst
+++ b/docs/en/api-guides/gnu-make-build-system.rst
@@ -40,11 +40,15 @@ To set the serial port for flashing/monitoring:
 - CMake based: ``idf.py -p (port) flash``
 - GNU Make based: ``make flash ESPPORT=/dev/ttyUSB0``, or set in ``menuconfig``.
 
+(Note: ``idf.py`` will also use the ``ESPPORT`` environment variable for a default serial port, if no ``-p`` argument is provided.)
+
 To set the baud rate for flashing:
 
 - CMake based: ``idf.py -b 921600 flash``
 - GNU Make based: ``make flash ESPBAUD=921600``, or set in ``menuconfig``.
 
+(Note: ``idf.py`` will also use the ``ESPBAUD`` environment variable for a default baud rate, if no ``-b`` argument is provided.)
+
 Porting GNU Make Based Components to CMake
 ==========================================
 
diff --git a/tools/idf.py b/tools/idf.py
index 3607a9003..d5fbf279a 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -346,8 +346,10 @@ def get_commandline_options():
 
 def main():
     parser = argparse.ArgumentParser(description='ESP-IDF build management tool')
-    parser.add_argument('-p', '--port', help="Serial port", default=None)
-    parser.add_argument('-b', '--baud', help="Baud rate", default=460800)
+    parser.add_argument('-p', '--port', help="Serial port",
+                        default=os.environ.get('ESPPORT', None))
+    parser.add_argument('-b', '--baud', help="Baud rate",
+                        default=os.environ.get('ESPBAUD', 460800))
     parser.add_argument('-C', '--project-dir', help="Project directory", default=os.getcwd())
     parser.add_argument('-B', '--build-dir', help="Build directory", default=None)
     parser.add_argument('-G', '--generator', help="Cmake generator", choices=GENERATOR_CMDS.keys())

From 526496ba207b675367b1f8058c2e81c9cea17294 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 8 May 2018 14:42:54 +0800
Subject: [PATCH 061/112] ci: Allow bot to control branch used for
 esp-idf-template

---
 tools/ci/test_build_system.sh       | 6 +++++-
 tools/ci/test_build_system_cmake.sh | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/tools/ci/test_build_system.sh b/tools/ci/test_build_system.sh
index e5ae4ea9f..efc3703b1 100755
--- a/tools/ci/test_build_system.sh
+++ b/tools/ci/test_build_system.sh
@@ -43,7 +43,11 @@ function run_tests()
     print_status "Cloning template from ${ESP_IDF_TEMPLATE_GIT}..."
     git clone ${ESP_IDF_TEMPLATE_GIT} template
     cd template
-    git checkout ${CI_BUILD_REF_NAME} || echo "Using esp-idf-template default branch..."
+    if [ -z $CHECKOUT_REF_SCRIPT ]; then
+        git checkout ${CI_BUILD_REF_NAME} || echo "Using esp-idf-template default branch..."
+    else
+        $CHECKOUT_REF_SCRIPT esp-idf-template
+    fi
 
     print_status "Updating template config..."
     make defconfig || exit $?
diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh
index 6f245f6b6..8484255a0 100755
--- a/tools/ci/test_build_system_cmake.sh
+++ b/tools/ci/test_build_system_cmake.sh
@@ -45,7 +45,11 @@ function run_tests()
     print_status "Cloning template from ${ESP_IDF_TEMPLATE_GIT}..."
     git clone ${ESP_IDF_TEMPLATE_GIT} template
     cd template
-    git checkout ${CI_BUILD_REF_NAME} || echo "Using esp-idf-template default branch..."
+    if [ -z $CHECKOUT_REF_SCRIPT ]; then
+        git checkout ${CI_BUILD_REF_NAME} || echo "Using esp-idf-template default branch..."
+    else
+        $CHECKOUT_REF_SCRIPT esp-idf-template
+    fi
 
     print_status "Try to clean fresh directory..."
     idf.py fullclean || exit $?

From 829e6c44f1831682f384c19def664cf516dae75d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 8 May 2018 22:05:43 +0800
Subject: [PATCH 062/112] cmake docs: Specify feature/cmake branch when cloning
 from Github

As mentioned here https://github.com/espressif/esp-idf/issues/1906#issuecomment-387377493
---
 docs/en/get-started/index.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index b87a55076..39148baad 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -129,7 +129,7 @@ For Windows Command Prompt users, the equivalent commands are::
 
     mkdir %userprofile%\esp
     cd %userprofile%\esp
-    git clone --recursive https://github.com/espressif/esp-idf.git
+    git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
 
 .. highlight:: bash
 .. note::
@@ -139,6 +139,12 @@ For Windows Command Prompt users, the equivalent commands are::
         cd esp-idf
         git submodule update --init
 
+.. note::
+
+   The CMake-based build system preview uses a different Git branch to the default. This branch is ``feature/cmake``. If you missed the ``--branch`` option when cloning then you can switch branches on the command line::
+
+         cd esp-idf
+         git checkout feature/cmake
 
 .. _get-started-setup-path:
 
@@ -211,7 +217,7 @@ For Windows Command Prompt users::
     cd %userprofile%\esp
     idf.py menuconfig
 
-.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`.
+.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf`.
 
 .. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work. You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
 

From 2f4079ebb2237c646ef49f9dd7e96a7c9552a098 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 7 May 2018 10:01:16 +0800
Subject: [PATCH 063/112] cmake: Hide serial port settings in menuconfig when
 using cmake

---
 Kconfig                                 | 3 +++
 components/esptool_py/Kconfig.projbuild | 4 ++++
 make/project_config.mk                  | 1 +
 tools/cmake/kconfig.cmake               | 4 +++-
 4 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/Kconfig b/Kconfig
index ac8a1db95..75606aa4f 100644
--- a/Kconfig
+++ b/Kconfig
@@ -4,6 +4,9 @@
 #
 mainmenu "Espressif IoT Development Framework Configuration"
 
+config IDF_CMAKE
+    bool
+    option env="IDF_CMAKE"
 
 menu "SDK tool configuration"
 config TOOLPREFIX
diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild
index c87d8adcf..e34d57759 100644
--- a/components/esptool_py/Kconfig.projbuild
+++ b/components/esptool_py/Kconfig.projbuild
@@ -2,6 +2,7 @@ menu "Serial flasher config"
 
 config ESPTOOLPY_PORT
 	string "Default serial port"
+    depends on !IDF_CMAKE
 	default "/dev/ttyUSB0"
 	help
         The serial port that's connected to the ESP chip. This can be overridden by setting the ESPPORT
@@ -11,6 +12,7 @@ config ESPTOOLPY_PORT
 
 choice ESPTOOLPY_BAUD
     prompt "Default baud rate"
+    depends on !IDF_CMAKE
     default ESPTOOLPY_BAUD_115200B
     help
         Default baud rate to use while communicating with the ESP chip. Can be overridden by
@@ -36,6 +38,7 @@ config ESPTOOLPY_BAUD_OTHER_VAL
 
 config ESPTOOLPY_BAUD
 	int
+    depends on !IDF_CMAKE
 	default 115200 if ESPTOOLPY_BAUD_115200B
 	default 230400 if ESPTOOLPY_BAUD_230400B
 	default 921600 if ESPTOOLPY_BAUD_921600B
@@ -44,6 +47,7 @@ config ESPTOOLPY_BAUD
 
 config ESPTOOLPY_COMPRESSED
 	bool "Use compressed upload"
+    depends on !IDF_CMAKE
 	default "y"
 	help
 		The flasher tool can send data compressed using zlib, letting the ROM on the ESP chip
diff --git a/make/project_config.mk b/make/project_config.mk
index 8f0006c79..613b203f7 100644
--- a/make/project_config.mk
+++ b/make/project_config.mk
@@ -43,6 +43,7 @@ define RunConf
 	cd $(BUILD_DIR_BASE); KCONFIG_AUTOHEADER=$(abspath $(BUILD_DIR_BASE)/include/sdkconfig.h) \
 	COMPONENT_KCONFIGS="$(COMPONENT_KCONFIGS)" KCONFIG_CONFIG=$(SDKCONFIG) \
 	COMPONENT_KCONFIGS_PROJBUILD="$(COMPONENT_KCONFIGS_PROJBUILD)" \
+	IDF_CMAKE=n \
 	$(KCONFIG_TOOL_DIR)/$1 $(IDF_PATH)/Kconfig
 endef
 
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index eeb8ce113..10894f6ad 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -83,7 +83,8 @@ function(kconfig_process_config)
         ${defaults_arg}
         --create-config-if-missing
         --env "COMPONENT_KCONFIGS=${kconfigs}"
-        --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}")
+        --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+        --env "IDF_CMAKE=y")
 
     # Generate the menuconfig target (uses C-based mconf tool, either prebuilt or via mconf target above)
     add_custom_target(menuconfig
@@ -93,6 +94,7 @@ function(kconfig_process_config)
         COMMAND ${CMAKE_COMMAND} -E env
         "COMPONENT_KCONFIGS=${kconfigs}"
         "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+        "IDF_CMAKE=y"
         "KCONFIG_CONFIG=${SDKCONFIG}"
         ${MCONF} ${ROOT_KCONFIG}
         VERBATIM

From cc104eb05b9276aab9b830263b0274e87dc5cd28 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 8 May 2018 15:33:21 +0800
Subject: [PATCH 064/112] cmake: Add sdkconfig.h directory to include paths
 list not just compiler args

Also move into 'build/config/' subdir, remove creation of empty include/config dir.
---
 components/esp32/CMakeLists.txt     |  4 ++--
 docs/en/api-guides/build-system.rst |  2 +-
 tools/cmake/idf_functions.cmake     |  2 --
 tools/cmake/kconfig.cmake           | 12 ++++++++----
 4 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 2c4fc7429..3a514d990 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -65,8 +65,8 @@ else()
     set(LD_DIR ${CMAKE_CURRENT_SOURCE_DIR}/ld)
     add_custom_command(
         OUTPUT esp32_out.ld
-        COMMAND "${CMAKE_C_COMPILER}" -C -P -x c -E -o esp32_out.ld -I ${CMAKE_BINARY_DIR} ${LD_DIR}/esp32.ld
-        MAIN_DEPENDENCY ${LD_DIR}/esp32.ld
+        COMMAND "${CMAKE_C_COMPILER}" -C -P -x c -E -o esp32_out.ld -I ${CONFIG_DIR} ${LD_DIR}/esp32.ld
+        MAIN_DEPENDENCY ${LD_DIR}/esp32.ld ${SDKCONFIG_H}
         COMMENT "Generating linker script..."
         VERBATIM)
     add_custom_target(esp32_linker_script DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld)
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index 2135ca0a2..d63c54c2e 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -825,7 +825,7 @@ For integration into IDEs and other build systems, when cmake runs the build pro
 - ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
 - ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
 - ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
-- ``sdkconfig.json`` is a JSON-formatted version of the project configuration values.
+- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
 
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _cmake: https://cmake.org
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index 3415f9da2..bd0aea6e5 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -98,8 +98,6 @@ function(idf_set_global_compiler_options)
     # go into the final binary so have no impact on size)
     add_compile_options(-ggdb)
 
-    add_compile_options("-I${CMAKE_BINARY_DIR}") # for sdkconfig.h
-
     # Enable ccache if it's on the path
     if(NOT CCACHE_DISABLE)
         find_program(CCACHE_FOUND ccache)
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 10894f6ad..f20002e1a 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -1,14 +1,18 @@
 include(ExternalProject)
 
 macro(kconfig_set_variables)
+    set(CONFIG_DIR ${CMAKE_BINARY_DIR}/config)
     set_default(SDKCONFIG ${PROJECT_PATH}/sdkconfig)
-    set(SDKCONFIG_HEADER ${CMAKE_BINARY_DIR}/sdkconfig.h)
-    set(SDKCONFIG_CMAKE ${CMAKE_BINARY_DIR}/sdkconfig.cmake)
-    set(SDKCONFIG_JSON ${CMAKE_BINARY_DIR}/sdkconfig.json)
+    set(SDKCONFIG_HEADER ${CONFIG_DIR}/sdkconfig.h)
+    set(SDKCONFIG_CMAKE ${CONFIG_DIR}/sdkconfig.cmake)
+    set(SDKCONFIG_JSON ${CONFIG_DIR}/sdkconfig.json)
 
     set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
 
     set_default(SDKCONFIG_DEFAULTS "${SDKCONFIG}.defaults")
+
+    # ensure all source files can include sdkconfig.h
+    include_directories("${CONFIG_DIR}")
 endmacro()
 
 if(CMAKE_HOST_WIN32)
@@ -48,7 +52,7 @@ endif()
 
 # Find all Kconfig files for all components
 function(kconfig_process_config)
-    file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/include/config")
+    file(MAKE_DIRECTORY "${CONFIG_DIR}")
     set(kconfigs)
     set(kconfigs_projbuild)
 

From f07c1ca94ff41e6d5ef325f454a75e450faec217 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 10 May 2018 18:11:45 +0800
Subject: [PATCH 065/112] docs: Fix some Windows Command Prompt paths

Reported in https://github.com/espressif/esp-idf/issues/1906
---
 docs/en/get-started/index.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 39148baad..8722a4286 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -214,7 +214,7 @@ Being in terminal window, go to directory of ``hello_world`` application by typi
 
 For Windows Command Prompt users::
 
-    cd %userprofile%\esp
+    cd %userprofile%\esp\hello_world
     idf.py menuconfig
 
 .. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf`.
@@ -369,7 +369,7 @@ Another solution is to update only what has changed. This method is useful if yo
 
 For Windows Command Prompt users::
 
-    cd %userprofile%\esp
+    cd %userprofile%\esp\esp-idf
     git pull
     git submodule update --init --recursive
 

From 979568fa0b71c9d818ffc04f656c8a007beff4e3 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 10 May 2018 18:15:03 +0800
Subject: [PATCH 066/112] docs: Separate "build and flash" into building then
 flashing

Explains idf.py build as mentioned here: https://github.com/espressif/esp-idf/issues/1906#issuecomment-387557050
---
 components/esp32/lib          |  2 +-
 docs/en/get-started/index.rst | 19 +++++++++++++++----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/components/esp32/lib b/components/esp32/lib
index 8cd9fd455..92a091649 160000
--- a/components/esp32/lib
+++ b/components/esp32/lib
@@ -1 +1 @@
-Subproject commit 8cd9fd455e98a5c818f2796b4b83107884b7874c
+Subproject commit 92a091649f7c8476580177e2a769b15d9c4c191f
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 8722a4286..14ba2f2c6 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -247,18 +247,29 @@ Here are couple of tips on navigation and use of ``menuconfig``:
 
 .. _get-started-build-flash:
 
-Build and Flash
-===============
+Build The Project and Flash
+===========================
 
 .. highlight:: bash
 
-Now you can build and flash the application. Run::
+Now you can build the project. Run::
+
+    idf.py build
+
+This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
+
+Flash To A Device
+=================
+
+Now you can flash the application to the ESP32 board. Run::
 
     idf.py -p PORT flash
 
 Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. (See :doc:`establish-serial-connection` for full details.)
 
-This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
+This step will flash the binaries that you just built to your ESP32 board.
+
+.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
 
 .. highlight:: none
 

From a1fac97f1a6e2e9a132ea87282d7d9370314273e Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 10 May 2018 19:15:19 +0800
Subject: [PATCH 067/112] cmake: Fix set_default using value from environment

Fixes issue with idf.py passing through Python interpreter, as reported in
https://github.com/espressif/esp-idf/issues/1924
---
 docs/en/api-guides/build-system.rst | 42 ++++++++++++++++++-----------
 tools/cmake/utilities.cmake         |  4 +--
 2 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index d63c54c2e..077e34b51 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -130,6 +130,8 @@ You can also use an IDE with CMake integration. The IDE will want to know the pa
 
 When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
 
+.. _example-project-structure:
+
 Example Project
 ===============
 
@@ -190,6 +192,8 @@ Minimal project::
       project(myProject)
 
 
+.. _project-mandatory-parts:
+
 Mandatory Parts
 ---------------
 
@@ -758,12 +762,23 @@ For project components (not part of ESP-IDF), there are a few options:
 
 The best option will depend on your particular project and its users.
 
+Build System Metadata
+=====================
+
+For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+
+- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
+- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
+- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
+- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
+- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
+
 .. _gnu-make-to-cmake:
 
 Migrating from ESP-IDF GNU Make System
 ======================================
 
-Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_SRCS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
+Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
 
 Automatic Conversion Tool
 -------------------------
@@ -782,6 +797,14 @@ It does so by running ``make`` to expand the ESP-IDF build system variables whic
 
 The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand.
 
+'main' is no longer a component
+-------------------------------
+
+In the GNU Make build system ``main`` is a component with a ``component.mk`` file like other components.
+
+Due to CMake requirements for building executables, ``main`` source files are now linked directly into the final binary. The source files in ``main`` must be listed in the ``MAIN_SRCS`` variable (see :ref:`project mandatory variables <project-mandatory-parts>` for more details). At least one source file has to be listed here (although it doesn't need to contain anything in particular).
+
+In general, it's better not to have too many source files in ``MAIN_SRCS``. If you find that you are adding many source files here, see if you reorganize and group some into project components (see the :ref:`example project structure <example-project-structure>`, above).
 
 No Longer Available in CMake
 ----------------------------
@@ -793,10 +816,10 @@ Some features are significantly different or removed in the CMake-based system.
 - ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
 - ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
 - ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
-- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically for files like linker scripts.
-- ``COMPONENT_SUBMODULES``: No longer used by ESP-IDF components, the build system will automatically enumerate all submodules in the repo.
+- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``.
+- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repo.
 - ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
-- ``COMPONENT_OBJS``: Used to be specified as a list of object files. Now specified as an optional list of source files via ``COMPONENT_SRCS``.
+- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``.
 - ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
 - ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
 - ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
@@ -816,17 +839,6 @@ No Longer Necessary
 
 It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
 
-Build System Metadata
-=====================
-
-For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
-
-- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
-- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
-- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
-- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
-- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
-
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _cmake: https://cmake.org
 .. _ninja: https://ninja-build.org
diff --git a/tools/cmake/utilities.cmake b/tools/cmake/utilities.cmake
index 791e3fbfa..e1c682c89 100644
--- a/tools/cmake/utilities.cmake
+++ b/tools/cmake/utilities.cmake
@@ -9,7 +9,7 @@
 #
 function(set_default variable default_value)
     if(NOT ${variable})
-        if($ENV{${variable}})
+        if(DEFINED ENV{${variable}} AND NOT "$ENV{${variable}}" STREQUAL "")
             set(${variable} $ENV{${variable}} PARENT_SCOPE)
         else()
             set(${variable} ${default_value} PARENT_SCOPE)
@@ -132,7 +132,7 @@ endmacro()
 # Append a single line to the file specified
 # The line ending is determined by the host OS
 function(file_append_line file line)
-    if(ENV{MSYSTEM} OR CMAKE_HOST_WIN32)
+    if(DEFINED ENV{MSYSTEM} OR CMAKE_HOST_WIN32)
         set(line_ending "\r\n")
     else() # unix
         set(line_ending "\n")

From be4956fe7c09ee39f45eb9dda308d372b7857e3b Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 11 May 2018 17:20:27 +0800
Subject: [PATCH 068/112] docs: Add some tips about setting the Python
 interpreter, and a specific check in idf.py

Don't show the "Python 2 interpreter" option in menuconfig when using CMake.

This is a stop-gap until we support Python 2 & 3 together in ESP-IDF (soon).

Closes https://github.com/espressif/esp-idf/issues/1924
---
 Kconfig                             |  1 +
 docs/en/api-guides/build-system.rst | 18 ++++++++++++++++++
 tools/idf.py                        |  3 +++
 tools/idf_monitor.py                |  4 ++--
 4 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/Kconfig b/Kconfig
index 75606aa4f..f6ebbc573 100644
--- a/Kconfig
+++ b/Kconfig
@@ -18,6 +18,7 @@ config TOOLPREFIX
 
 config PYTHON
     string "Python 2 interpreter"
+    depends on !IDF_CMAKE
     default "python"
     help
         The executable name/path that is used to run python. On some systems Python 2.x
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index 077e34b51..f32cc9eb3 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -130,6 +130,21 @@ You can also use an IDE with CMake integration. The IDE will want to know the pa
 
 When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
 
+.. setting-python-interpreter:
+
+Setting the Python Interpreter
+------------------------------
+
+Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems.
+
+If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command.
+
+If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter.
+
+If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter.
+
+To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version.
+
 .. _example-project-structure:
 
 Example Project
@@ -860,3 +875,6 @@ It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SR
 .. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
 .. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
 .. _quirc: https://github.com/dlbeer/quirc
+.. _pyenv: https://github.com/pyenv/pyenv#README
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+
diff --git a/tools/idf.py b/tools/idf.py
index d5fbf279a..bd7b9fe23 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -345,6 +345,9 @@ def get_commandline_options():
 
 
 def main():
+    if sys.version_info[0] != 2 or sys.version_info[1] != 7:
+        raise FatalError("ESP-IDF currently only supports Python 2.7, and this is Python %d.%d.%d. Search for 'Setting the Python Interpreter' in the ESP-IDF docs for some tips to handle this." % sys.version_info[:3])
+
     parser = argparse.ArgumentParser(description='ESP-IDF build management tool')
     parser.add_argument('-p', '--port', help="Serial port",
                         default=os.environ.get('ESPPORT', None))
diff --git a/tools/idf_monitor.py b/tools/idf_monitor.py
index 29347efc9..278626657 100755
--- a/tools/idf_monitor.py
+++ b/tools/idf_monitor.py
@@ -3,8 +3,8 @@
 # esp-idf serial output monitor tool. Does some helpful things:
 # - Looks up hex addresses in ELF file with addr2line
 # - Reset ESP32 via serial RTS line (Ctrl-T Ctrl-R)
-# - Run "make/idf.py flash" (Ctrl-T Ctrl-F)
-# - Run "make/idf.py app-flash" (Ctrl-T Ctrl-A)
+# - Run "make (or idf.py) flash" (Ctrl-T Ctrl-F)
+# - Run "make (or idf.py) app-flash" (Ctrl-T Ctrl-A)
 # - If gdbstub output is detected, gdb is automatically loaded
 #
 # Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD

From ed1f4e50df605fcd2dbbe38d9f445563e0f9c559 Mon Sep 17 00:00:00 2001
From: Nicola Lunghi <25422924+nicola-lunghi@users.noreply.github.com>
Date: Fri, 11 May 2018 16:54:45 +0100
Subject: [PATCH 069/112] cmakelists: move spi_flash to COMPONENT_REQUIRES

in the include file esp_ota_ops.h "esp_partition.h" is included.
This is from spi_flash so component that requires app_update also will need that

this fixes this error:

  In file included from ../components/esp32-homie/ota.c:11:0:
  /esp-idf/components/app_update/include/esp_ota_ops.h:22:27: fatal error: esp_partition.h: No such file or directory

Signed-off-by: Nicola Lunghi <25422924+nicola-lunghi@users.noreply.github.com>

Merges https://github.com/espressif/esp-idf/pull/1947
---
 components/app_update/CMakeLists.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt
index 44663f68e..e1401c685 100644
--- a/components/app_update/CMakeLists.txt
+++ b/components/app_update/CMakeLists.txt
@@ -1,7 +1,7 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
-set(COMPONENT_REQUIRES "")
-set(COMPONENT_PRIV_REQUIRES bootloader_support spi_flash)
+set(COMPONENT_REQUIRES spi_flash)
+set(COMPONENT_PRIV_REQUIRES bootloader_support)
 
 register_component()

From 8cf82be9178d2660401bcf45cd22849458eac571 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 17 May 2018 11:55:40 +0800
Subject: [PATCH 070/112] esp32: Component needs public dependency on
 tcpip_adapter

Because of esp_event.h

Closes https://github.com/espressif/esp-idf/issues/1954
---
 components/esp32/CMakeLists.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/components/esp32/CMakeLists.txt b/components/esp32/CMakeLists.txt
index 3a514d990..42e14ba19 100644
--- a/components/esp32/CMakeLists.txt
+++ b/components/esp32/CMakeLists.txt
@@ -20,10 +20,12 @@ else()
     set(COMPONENT_SRCDIRS ". hwcrypto")
     set(COMPONENT_ADD_INCLUDEDIRS "include")
 
-    set(COMPONENT_REQUIRES driver)  # required because esp_sleep.h uses gpio_num_t & touch_pad_t
+    set(COMPONENT_REQUIRES driver tcpip_adapter)
+    # driver is a public requirement because esp_sleep.h uses gpio_num_t & touch_pad_t
+    # tcpip_adapter is a public requirement because esp_event.h uses tcpip_adapter types
     set(COMPONENT_PRIV_REQUIRES
         app_trace bootloader_support ethernet log mbedtls nvs_flash
-        pthread spi_flash tcpip_adapter vfs wpa_supplicant xtensa-debug-module)
+        pthread spi_flash vfs wpa_supplicant xtensa-debug-module)
 
     register_component()
 

From 61aff5162caaa32d8fbcb5be48f51e6352f87287 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 17 May 2018 12:23:49 +0800
Subject: [PATCH 071/112] mconf: Don't print a recommendation to use 'make' if
 CMake build system is in use

Also add some cmake dependencies to rebuild mconf if its source files change.
---
 tools/cmake/kconfig.cmake | 11 ++++++++++-
 tools/kconfig/mconf.c     | 14 ++++++++++----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index f20002e1a..7d1f51304 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -38,7 +38,7 @@ if(NOT MCONF)
     #
     set(MCONF kconfig_bin/mconf)
 
-    externalproject_add(mconf
+    Externalproject_Add(mconf
         SOURCE_DIR ${IDF_PATH}/tools/kconfig
         CONFIGURE_COMMAND ""
         BINARY_DIR "kconfig_bin"
@@ -47,7 +47,16 @@ if(NOT MCONF)
         INSTALL_COMMAND ""
         EXCLUDE_FROM_ALL 1
         )
+
+    file(GLOB mconf_srcfiles ${IDF_PATH}/tools/kconfig/*.c)
+    ExternalProject_Add_StepDependencies(mconf build
+        ${mconf_srcfiles}
+        ${IDF_PATH}/tools/kconfig/Makefile
+        ${CMAKE_CURRENT_LIST_FILE})
+    unset(mconf_srcfiles)
+
     set(menuconfig_depends DEPENDS mconf)
+
 endif()
 
 # Find all Kconfig files for all components
diff --git a/tools/kconfig/mconf.c b/tools/kconfig/mconf.c
index 315ce2c7c..75fe11635 100644
--- a/tools/kconfig/mconf.c
+++ b/tools/kconfig/mconf.c
@@ -980,11 +980,17 @@ static int handle_exit(void)
 		}
 		/* fall through */
 	case -1:
-		if (!silent)
+		if (!silent) {
+			const char *is_cmake = getenv("IDF_CMAKE");
+			const char *build_msg;
+			if (is_cmake && is_cmake[0] == 'y')
+				build_msg = _("Ready to use CMake (or 'idf.py build') to build the project.");
+			else
+				build_msg = _("Execute 'make' to start the build or try 'make help'.");
 			printf(_("\n\n"
-				 "*** End of the configuration.\n"
-				 "*** Execute 'make' to start the build or try 'make help'."
-				 "\n\n"));
+					 "*** End of the configuration.\n"
+					 "*** %s\n\n"), build_msg);
+		}
 		res = 0;
 		break;
 	default:

From 6cc597151683b77bab5d0cefec34b9c06f321240 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 17 May 2018 14:08:31 +0800
Subject: [PATCH 072/112] docs: Add some clarification about ~/.profile

---
 docs/en/get-started/add-idf_path-to-profile.rst | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst
index f775f901f..5ba2fad5b 100644
--- a/docs/en/get-started/add-idf_path-to-profile.rst
+++ b/docs/en/get-started/add-idf_path-to-profile.rst
@@ -39,16 +39,20 @@ If you got here from section :ref:`get-started-setup-path`, while installing s/w
 Linux and MacOS
 ---------------
 
-Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to ``~/.profile`` file::
+Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
 
     export IDF_PATH=~/esp/esp-idf
     export PATH="$PATH:$IDF_PATH/tools"
 
+.. note::
+
+   ``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
+
 Log off and log in back to make this change effective.
 
 .. note::
 
-    If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
+    Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
 
 Run the following command to check if ``IDF_PATH`` is set::
 

From 11980a9ad49ddda832a4ff72c61cb65333d0a5d6 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 17 May 2018 14:08:42 +0800
Subject: [PATCH 073/112] docs: Add port argument to idf.py monitor

---
 docs/en/get-started/index.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 14ba2f2c6..79ada7188 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -314,9 +314,9 @@ If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out th
 Monitor
 =======
 
-To see if "hello_world" application is indeed running, type ``idf.py monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
+To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
 
-    $ idf.py monitor
+    $ idf.py -p /dev/ttyUSB0 monitor
     Running idf_monitor in directory [...]/esp/hello_world/build
     Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
     --- idf_monitor on /dev/ttyUSB0 115200 ---

From f6cd55d2acf24f4ac702722f0ca9ff687f9b9465 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 24 May 2018 13:32:34 +1000
Subject: [PATCH 074/112] config: Rename mconf to mconf-idf & conf to conf-idf

These versions of conf/mconf are forked from the upstream, and the CMake system allows mconf-idf to
be installed externally on the path. So the best option is to rename.

Includes changes to Windows installer for v1.1
---
 docs/en/get-started/windows-setup-scratch.rst |  6 +--
 docs/en/get-started/windows-setup.rst         |  6 +--
 make/project_config.mk                        | 22 +++++------
 tools/cmake/kconfig.cmake                     | 30 +++++++++-----
 tools/kconfig/.gitignore                      |  2 +
 tools/kconfig/Makefile                        | 39 ++++++++++---------
 tools/windows/tool_setup/build_installer.sh   |  4 +-
 tools/windows/tool_setup/idf_tool_setup.iss   | 18 ++++-----
 8 files changed, 70 insertions(+), 57 deletions(-)

diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst
index 908897613..f7ee77081 100644
--- a/docs/en/get-started/windows-setup-scratch.rst
+++ b/docs/en/get-started/windows-setup-scratch.rst
@@ -45,10 +45,10 @@ Once Python is installed, open a Windows Command Prompt from the Start menu and
 
   pip install pyserial
 
-MConf
-^^^^^
+MConf for IDF
+^^^^^^^^^^^^^
 
-Download the ESP-IDF customized version of the configuration tool mconf from the `mconf releases page <mconf>`_.
+Download the configuration tool mconf-idf from the `kconfig-frontends releases page <mconf-idf>`_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF.
 
 This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
 
diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst
index c9e1b7011..9b12e9d90 100644
--- a/docs/en/get-started/windows-setup.rst
+++ b/docs/en/get-started/windows-setup.rst
@@ -23,9 +23,9 @@ ESP-IDF Tools Installer
 
 The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
 
-https://dl.espressif.com/dl/esp-idf-tools-setup-1.0.exe
+https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe
 
-The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a customized configuration tool called mconf. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
+The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
 
 By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
 
@@ -68,5 +68,5 @@ For advanced users who want to customize the install process:
 .. _ninja: https://ninja-build.org/
 .. _Python: https://www.python.org/downloads/windows/
 .. _Git for Windows: https://gitforwindows.org/
-.. _mconf: https://github.com/espressif/kconfig-frontends/releases/
+.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
 .. _Github Desktop: https://desktop.github.com/
diff --git a/make/project_config.mk b/make/project_config.mk
index 613b203f7..50cf139e6 100644
--- a/make/project_config.mk
+++ b/make/project_config.mk
@@ -15,11 +15,11 @@ SDKCONFIG ?= $(PROJECT_PATH)/sdkconfig
 # overrides (usually used for esp-idf examples)
 SDKCONFIG_DEFAULTS ?= $(PROJECT_PATH)/sdkconfig.defaults
 
-# Workaround to run make parallel (-j). mconf and conf cannot be made simultaneously
-$(KCONFIG_TOOL_DIR)/mconf: $(KCONFIG_TOOL_DIR)/conf
+# Workaround to run make parallel (-j). mconf-idf and conf-idf cannot be made simultaneously
+$(KCONFIG_TOOL_DIR)/mconf-idf: $(KCONFIG_TOOL_DIR)/conf-idf
 
 # reset MAKEFLAGS as the menuconfig makefile uses implicit compile rules
-$(KCONFIG_TOOL_DIR)/mconf $(KCONFIG_TOOL_DIR)/conf: $(wildcard $(KCONFIG_TOOL_DIR)/*.c)
+$(KCONFIG_TOOL_DIR)/mconf-idf $(KCONFIG_TOOL_DIR)/conf-idf: $(wildcard $(KCONFIG_TOOL_DIR)/*.c)
 	MAKEFLAGS="" CC=$(HOSTCC) LD=$(HOSTLD) \
 	$(MAKE) -C $(KCONFIG_TOOL_DIR)
 
@@ -36,7 +36,7 @@ $(SDKCONFIG): defconfig
 endif
 endif
 
-# macro for the commands to run kconfig tools conf or mconf.
+# macro for the commands to run kconfig tools conf-idf or mconf-idf.
 # $1 is the name (& args) of the conf tool to run
 define RunConf
 	mkdir -p $(BUILD_DIR_BASE)/include/config
@@ -59,7 +59,7 @@ ifndef MAKE_RESTARTS
 # depend on any prerequisite that may cause a make restart as part of
 # the prerequisite's own recipe.
 
-menuconfig: $(KCONFIG_TOOL_DIR)/mconf
+menuconfig: $(KCONFIG_TOOL_DIR)/mconf-idf
 	$(summary) MENUCONFIG
 ifdef BATCH_BUILD
 	@echo "Can't run interactive configuration inside non-interactive build process."
@@ -68,25 +68,25 @@ ifdef BATCH_BUILD
 	@echo "See esp-idf documentation for more details."
 	@exit 1
 else
-	$(call RunConf,mconf)
+	$(call RunConf,mconf-idf)
 endif
 
 # defconfig creates a default config, based on SDKCONFIG_DEFAULTS if present
-defconfig: $(KCONFIG_TOOL_DIR)/conf
+defconfig: $(KCONFIG_TOOL_DIR)/conf-idf
 	$(summary) DEFCONFIG
 ifneq ("$(wildcard $(SDKCONFIG_DEFAULTS))","")
 	cat $(SDKCONFIG_DEFAULTS) >> $(SDKCONFIG)  # append defaults to sdkconfig, will override existing values
 endif
-	$(call RunConf,conf --olddefconfig)
+	$(call RunConf,conf-idf --olddefconfig)
 
 # if neither defconfig or menuconfig are requested, use the GENCONFIG rule to
 # ensure generated config files are up to date
-$(SDKCONFIG_MAKEFILE) $(BUILD_DIR_BASE)/include/sdkconfig.h: $(KCONFIG_TOOL_DIR)/conf $(SDKCONFIG) $(COMPONENT_KCONFIGS) $(COMPONENT_KCONFIGS_PROJBUILD) | $(call prereq_if_explicit,defconfig) $(call prereq_if_explicit,menuconfig)
+$(SDKCONFIG_MAKEFILE) $(BUILD_DIR_BASE)/include/sdkconfig.h: $(KCONFIG_TOOL_DIR)/conf-idf $(SDKCONFIG) $(COMPONENT_KCONFIGS) $(COMPONENT_KCONFIGS_PROJBUILD) | $(call prereq_if_explicit,defconfig) $(call prereq_if_explicit,menuconfig)
 	$(summary) GENCONFIG
 ifdef BATCH_BUILD  # can't prompt for new config values like on terminal
-	$(call RunConf,conf --olddefconfig)
+	$(call RunConf,conf-idf --olddefconfig)
 endif
-	$(call RunConf,conf --silentoldconfig)
+	$(call RunConf,conf-idf --silentoldconfig)
 	touch $(SDKCONFIG_MAKEFILE) $(BUILD_DIR_BASE)/include/sdkconfig.h  # ensure newer than sdkconfig
 
 else  # "$(MAKE_RESTARTS)" != ""
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 7d1f51304..478b73e34 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -16,16 +16,26 @@ macro(kconfig_set_variables)
 endmacro()
 
 if(CMAKE_HOST_WIN32)
-    # Prefer a prebuilt mconf on Windows
+    # Prefer a prebuilt mconf-idf on Windows
     find_program(WINPTY winpty)
-    find_program(MCONF mconf)
+    find_program(MCONF mconf-idf)
+
+    # Fall back to the old binary which was called 'mconf' not 'mconf-idf'
+    if(NOT MCONF)
+        find_program(MCONF mconf)
+        if(MCONF)
+            message(WARNING "Falling back to mconf binary '${MCONF}' not mconf-idf. "
+                "This is probably because an old version of IDF mconf is installed and this is fine. "
+                "However if there are config problems please check the Getting Started guide for your platform.")
+        endif()
+    endif()
 
     if(NOT MCONF)
         find_program(NATIVE_GCC gcc)
         if(NOT NATIVE_GCC)
             message(FATAL_ERROR
-                "Windows requires a prebuilt ESP-IDF-specific mconf for your platform "
-                "on the PATH, or an MSYS2 version of gcc on the PATH to build mconf. "
+                "Windows requires a prebuilt mconf-idf for your platform "
+                "on the PATH, or an MSYS2 version of gcc on the PATH to build mconf-idf. "
                 "Consult the setup docs for ESP-IDF on Windows.")
         endif()
     elseif(WINPTY)
@@ -36,26 +46,26 @@ endif()
 if(NOT MCONF)
     # Use the existing Makefile to build mconf (out of tree) when needed
     #
-    set(MCONF kconfig_bin/mconf)
+    set(MCONF kconfig_bin/mconf-idf)
 
-    Externalproject_Add(mconf
+    externalproject_add(mconf-idf
         SOURCE_DIR ${IDF_PATH}/tools/kconfig
         CONFIGURE_COMMAND ""
         BINARY_DIR "kconfig_bin"
-        BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf
+        BUILD_COMMAND make -f ${IDF_PATH}/tools/kconfig/Makefile mconf-idf
         BUILD_BYPRODUCTS ${MCONF}
         INSTALL_COMMAND ""
         EXCLUDE_FROM_ALL 1
         )
 
     file(GLOB mconf_srcfiles ${IDF_PATH}/tools/kconfig/*.c)
-    ExternalProject_Add_StepDependencies(mconf build
+    externalproject_add_stepdependencies(mconf-idf build
         ${mconf_srcfiles}
         ${IDF_PATH}/tools/kconfig/Makefile
         ${CMAKE_CURRENT_LIST_FILE})
     unset(mconf_srcfiles)
 
-    set(menuconfig_depends DEPENDS mconf)
+    set(menuconfig_depends DEPENDS mconf-idf)
 
 endif()
 
@@ -99,7 +109,7 @@ function(kconfig_process_config)
         --env "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
         --env "IDF_CMAKE=y")
 
-    # Generate the menuconfig target (uses C-based mconf tool, either prebuilt or via mconf target above)
+    # Generate the menuconfig target (uses C-based mconf-idf tool, either prebuilt or via mconf-idf target above)
     add_custom_target(menuconfig
         ${menuconfig_depends}
         # create any missing config file, with defaults if necessary
diff --git a/tools/kconfig/.gitignore b/tools/kconfig/.gitignore
index 1950c8cb1..641b9e576 100644
--- a/tools/kconfig/.gitignore
+++ b/tools/kconfig/.gitignore
@@ -16,7 +16,9 @@ gconf.glade.h
 # configuration programs
 #
 conf
+conf-idf
 mconf
+mconf-idf
 nconf
 qconf
 gconf
diff --git a/tools/kconfig/Makefile b/tools/kconfig/Makefile
index c8a56abdd..c8f8ba014 100644
--- a/tools/kconfig/Makefile
+++ b/tools/kconfig/Makefile
@@ -43,7 +43,7 @@ endif
 endif # MING32
 endif # MSYSTEM
 
-default: mconf conf
+default: mconf-idf conf-idf
 
 xconfig: qconf
 	$< $(silent) $(Kconfig)
@@ -51,41 +51,41 @@ xconfig: qconf
 gconfig: gconf
 	$< $(silent) $(Kconfig)
 
-menuconfig: mconf
+menuconfig: mconf-idf
 	$< $(silent) $(Kconfig)
 
-config: conf
+config: conf-idf
 	$< $(silent) --oldaskconfig $(Kconfig)
 
 nconfig: nconf
 	$< $(silent) $(Kconfig)
 
-silentoldconfig: conf
+silentoldconfig: conf-idf
 	mkdir -p include/config include/generated
 	$< $(silent) --$@ $(Kconfig)
 
-localyesconfig localmodconfig: streamline_config.pl conf
+localyesconfig localmodconfig: streamline_config.pl conf-idf
 	mkdir -p include/config include/generated
 	perl $< --$@ . $(Kconfig) > .tmp.config
 	if [ -f .config ]; then 					\
 			cmp -s .tmp.config .config ||			\
 			(mv -f .config .config.old.1;			\
 			 mv -f .tmp.config .config;			\
-			 conf $(silent) --silentoldconfig $(Kconfig); \
+			 conf-idf $(silent) --silentoldconfig $(Kconfig); \
 			 mv -f .config.old.1 .config.old)		\
 	else								\
 			mv -f .tmp.config .config;			\
-			conf $(silent) --silentoldconfig $(Kconfig); \
+			conf-idf $(silent) --silentoldconfig $(Kconfig); \
 	fi
 	rm -f .tmp.config
 
 
-# These targets map 1:1 to the commandline options of 'conf'
+# These targets map 1:1 to the commandline options of 'conf-idf'
 simple-targets := oldconfig allnoconfig allyesconfig allmodconfig \
 	alldefconfig randconfig listnewconfig olddefconfig
 PHONY += $(simple-targets)
 
-$(simple-targets): conf
+$(simple-targets): conf-idf
 	$< $(silent) --$@ $(Kconfig)
 
 PHONY += oldnoconfig savedefconfig defconfig
@@ -95,10 +95,10 @@ PHONY += oldnoconfig savedefconfig defconfig
 # counter-intuitive name.
 oldnoconfig: olddefconfig
 
-savedefconfig: conf
+savedefconfig: conf-idf
 	$< $(silent) --$@=defconfig $(Kconfig)
 
-defconfig: conf
+defconfig: conf-idf
 ifeq ($(KBUILD_DEFCONFIG),)
 	$< $(silent) --defconfig $(Kconfig)
 else
@@ -111,12 +111,12 @@ else
 endif
 endif
 
-%_defconfig: conf
+%_defconfig: conf-idf
 	$< $(silent) --defconfig=arch/$(SRCARCH)/configs/$@ $(Kconfig)
 
 configfiles=$(wildcard $(srctree)/kernel/configs/$@ $(srctree)/arch/$(SRCARCH)/configs/$@)
 
-%.config: conf
+%.config: conf-idf
 	$(if $(call configfiles),, $(error No configuration exists for this target on this architecture))
 	$(CONFIG_SHELL) $(srctree)/scripts/kconfig/merge_config.sh -m .config $(configfiles)
 	+yes "" | $(MAKE) -f $(srctree)/Makefile oldconfig
@@ -178,10 +178,10 @@ lxdialog/%.o: $(SRCDIR)/lxdialog/%.c
 
 # ===========================================================================
 # Shared Makefile for the various kconfig executables:
-# conf:	  Used for defconfig, oldconfig and related targets
+# conf-idf:	  Used for defconfig, oldconfig and related targets
 # nconf:  Used for the nconfig target.
 #         Utilizes ncurses
-# mconf:  Used for the menuconfig target
+# mconf-idf:  Used for the menuconfig target
 #         Utilizes the lxdialog package
 # qconf:  Used for the xconfig target
 #         Based on Qt which needs to be installed to compile it
@@ -200,14 +200,15 @@ qconf-cxxobjs	:= qconf.o
 qconf-objs	:= zconf.tab.o
 gconf-objs	:= gconf.o zconf.tab.o
 
-hostprogs-y := conf nconf mconf kxgettext qconf gconf
+hostprogs-y := conf-idf nconf mconf-idf kxgettext qconf gconf
 
 all-objs := $(conf-objs) $(mconf-objs) $(lxdialog)
 all-deps := $(all-objs:.o=.d)
 
 clean-files	:= qconf.moc .tmp_qtcheck .tmp_gtkcheck
 clean-files	+= zconf.tab.c zconf.lex.c zconf.hash.c gconf.glade.h
-clean-files += $(all-objs) $(all-deps) conf mconf
+clean-files += $(all-objs) $(all-deps) conf-idf mconf-idf conf mconf
+# (note: cleans both mconf & conf (old names) and conf-idf & mconf-idf (new names))
 
 # Check that we have the required ncurses stuff installed for lxdialog (menuconfig)
 PHONY += dochecklxdialog
@@ -324,10 +325,10 @@ gconf.glade.h: gconf.glade
 	gconf.glade
 
 
-mconf: lxdialog $(mconf-objs)
+mconf-idf: lxdialog $(mconf-objs)
 	$(CC) -o $@ $(mconf-objs) $(LOADLIBES_mconf)
 
-conf: $(conf-objs)
+conf-idf: $(conf-objs)
 	$(CC) -o $@ $(conf-objs) $(LOADLIBES_conf)
 
 zconf.tab.c: zconf.lex.c
diff --git a/tools/windows/tool_setup/build_installer.sh b/tools/windows/tool_setup/build_installer.sh
index 8733629b6..8dc21f1de 100755
--- a/tools/windows/tool_setup/build_installer.sh
+++ b/tools/windows/tool_setup/build_installer.sh
@@ -13,14 +13,14 @@ set -e
 cd `dirname $0`
 pushd dl
 wget --continue "https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip"
-wget --continue "https://github.com/espressif/kconfig-frontends/releases/download/v4.6.0.0-idf-20180319/mconf-v4.6.0.0-idf-20180319-win32.zip"
+wget --continue "https://github.com/espressif/kconfig-frontends/releases/download/v4.6.0.0-idf-20180525/mconf-v4.6.0.0-idf-20180525-win32.zip"
 wget --continue "https://github.com/ninja-build/ninja/releases/download/v1.8.2/ninja-win.zip"
 popd
 
 rm -rf input/*
 pushd input
 unzip ../dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
-unzip ../dl/mconf-v4.6.0.0-idf-20180319-win32.zip
+unzip ../dl/mconf-v4.6.0.0-idf-20180525-win32.zip
 unzip ../dl/ninja-win.zip
 popd
 
diff --git a/tools/windows/tool_setup/idf_tool_setup.iss b/tools/windows/tool_setup/idf_tool_setup.iss
index 8c888e8f0..551c5abcb 100644
--- a/tools/windows/tool_setup/idf_tool_setup.iss
+++ b/tools/windows/tool_setup/idf_tool_setup.iss
@@ -2,8 +2,8 @@
 
 [Setup]
 AppName=ESP-IDF Tools
-AppVersion=1.0
-OutputBaseFilename=esp-idf-tools-setup-1.0
+AppVersion=1.1
+OutputBaseFilename=esp-idf-tools-setup-1.1
 
 DefaultDirName={pf}\Espressif\ESP-IDF Tools
 DefaultGroupName=ESP-IDF Tools
@@ -22,7 +22,7 @@ Name: "custom"; Description: "Custom installation"; Flags: iscustom
 
 [Components]
 Name: toolchain; Description: ESP32 Xtensa GCC Cross-Toolchain; Types: full custom;
-Name: mconf; Description: ESP-IDF console menuconfig tool; Types: full custom;
+Name: mconf_idf; Description: ESP-IDF console menuconfig tool; Types: full custom;
 Name: ninja; Description: Install Ninja build v1.8.2; Types: full custom
 
 [Tasks]
@@ -42,7 +42,7 @@ Name: python64; Description: Download and Run Python 2.7.14 Installer and instal
 
 [Files]
 Components: toolchain; Source: "input\xtensa-esp32-elf\*"; DestDir: "{app}\toolchain\"; Flags: recursesubdirs;
-Components: mconf; Source: "input\mconf-v4.6.0.0-idf-20180319-win32\*"; DestDir: "{app}\mconf\";
+Components: mconf_idf; Source: "input\mconf-v4.6.0.0-idf-20180525-win32\*"; DestDir: "{app}\mconf-idf\";
 Components: ninja; Source: "input\ninja.exe"; DestDir: "{app}";
 
 [Run]
@@ -61,13 +61,13 @@ Root: HKCU; Subkey: "Environment"; \
     ValueType: expandsz; ValueName: "Path"; ValueData: "{app};{olddata}"; Check: not IsInPath('{app}'); \
     Components: ninja; Tasks: addpath\user
 
-; mconf path
+; mconf-idf path
 Root: HKLM; Subkey: "SYSTEM\CurrentControlSet\Control\Session Manager\Environment"; \
-    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf;{olddata}"; Check: not IsInPath('{app}\mconf'); \
-    Components: mconf; Tasks: addpath\allusers
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf-idf;{olddata}"; Check: not IsInPath('{app}\mconf-idf'); \
+    Components: mconf_idf; Tasks: addpath\allusers
 Root: HKCU; Subkey: "Environment"; \
-    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf;{olddata}"; Check: not IsInPath('{app}\mconf'); \
-    Components: mconf; Tasks: addpath\user
+    ValueType: expandsz; ValueName: "Path"; ValueData: "{app}\mconf-idf;{olddata}"; Check: not IsInPath('{app}\mconf-idf'); \
+    Components: mconf_idf; Tasks: addpath\user
 
 ; toolchain path
 Root: HKLM; Subkey: "SYSTEM\CurrentControlSet\Control\Session Manager\Environment"; \

From 955e84a3bc4fb4540c26c8bd8e61b1d4b424f82a Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 24 May 2018 13:48:38 +1000
Subject: [PATCH 075/112] docs: Add some clarifications for Mac OS users

---
 docs/en/get-started/establish-serial-connection.rst | 2 ++
 docs/en/get-started/macos-setup.rst                 | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
index 363de1cce..e7f8e9d96 100644
--- a/docs/en/get-started/establish-serial-connection.rst
+++ b/docs/en/get-started/establish-serial-connection.rst
@@ -54,6 +54,8 @@ MacOS ::
     ls /dev/cu.*
 
 
+.. note: MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
+
 .. _linux-dialout-group:
 
 Adding user to ``dialout`` on Linux
diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst
index a699c3bef..70142482e 100644
--- a/docs/en/get-started/macos-setup.rst
+++ b/docs/en/get-started/macos-setup.rst
@@ -8,6 +8,8 @@ Standard Setup of Toolchain for Mac OS
 Install Prerequisites
 =====================
 
+ESP-IDF will use the version of Python installed by default on Mac OS.
+
 - install pip::
 
     sudo easy_install pip

From 580cfeaaaec17649f54fd5b77b7dcf3f87caf76e Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 24 May 2018 16:05:31 +1000
Subject: [PATCH 076/112] idf.py: Print flashing steps at the end of each build

---
 components/esptool_py/CMakeLists.txt          |  2 +-
 components/esptool_py/flash_app_args.in       |  3 -
 .../esptool_py/flash_partition_table_args.in  |  3 -
 components/esptool_py/flasher_args.json.in    |  8 ++-
 docs/en/get-started/index.rst                 | 23 ++++++++
 tools/idf.py                                  | 57 +++++++++++++++++--
 6 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/components/esptool_py/CMakeLists.txt b/components/esptool_py/CMakeLists.txt
index 0d62557c8..690763934 100644
--- a/components/esptool_py/CMakeLists.txt
+++ b/components/esptool_py/CMakeLists.txt
@@ -1,7 +1,7 @@
 register_config_only_component()
 
 # Generate pre-canned flasher args files suitable for passing to esptool.py
-foreach(part project app bootloader)
+foreach(part project app bootloader partition_table)
     configure_file(
         "${CMAKE_CURRENT_LIST_DIR}/flash_${part}_args.in"
         "${CMAKE_BINARY_DIR}/flash_${part}_args"
diff --git a/components/esptool_py/flash_app_args.in b/components/esptool_py/flash_app_args.in
index 7cc24a638..1e2fa31c2 100644
--- a/components/esptool_py/flash_app_args.in
+++ b/components/esptool_py/flash_app_args.in
@@ -1,4 +1 @@
---flash_mode ${ESPFLASHMODE}
---flash_size ${ESPFLASHSIZE}
---flash_freq ${ESPFLASHFREQ}
 ${CONFIG_APP_OFFSET} ${PROJECT_NAME}.bin
diff --git a/components/esptool_py/flash_partition_table_args.in b/components/esptool_py/flash_partition_table_args.in
index f5bbe084c..0983e11c4 100644
--- a/components/esptool_py/flash_partition_table_args.in
+++ b/components/esptool_py/flash_partition_table_args.in
@@ -1,4 +1 @@
---flash_mode ${ESPFLASHMODE}
---flash_size ${ESPFLASHSIZE}
---flash_freq ${ESPFLASHFREQ}
 0x8000 partition_table/partition-table.bin
diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
index 0266316ea..55e3a93a5 100644
--- a/components/esptool_py/flasher_args.json.in
+++ b/components/esptool_py/flasher_args.json.in
@@ -7,5 +7,11 @@
         "0x8000" : "partition_table/partition-table.bin",
         "${CONFIG_APP_OFFSET}" : "${PROJECT_NAME}.bin",
         "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}"
-    }
+    },
+    "bootloader" :      { "offset" : "0x1000",
+                          "file" : "bootloader/bootloader.bin" },
+    "app" :             { "offset" : "${CONFIG_APP_OFFSET}",
+                          "file" : "${PROJECT_NAME}.bin" },
+    "partition_table" : { "offset" : "0x8000",
+                          "file" : "partition_table/partition-table.bin" }
 }
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 79ada7188..8542bd37a 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -258,6 +258,29 @@ Now you can build the project. Run::
 
 This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
 
+.. highlight: none
+
+::
+   $ idf.py build
+   Running cmake in directory /path/to/hello_world/build
+   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
+   Warn about uninitialized values.
+   -- Found Git: /usr/bin/git (found version "2.17.0")
+   -- Building empty aws_iot component due to configuration
+   -- Component names: ...
+   -- Component paths: ...
+   
+   ... (more lines of build system output)
+   
+   [527/527] Generating hello-world.bin
+   esptool.py v2.3.1
+   
+   Project build complete. To flash, run this command:
+   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
+   or run 'idf.py flash'
+
+If there are no errors, the build will finish by generating the firmware binary .bin file.
+
 Flash To A Device
 =================
 
diff --git a/tools/idf.py b/tools/idf.py
index bd7b9fe23..8b2c058fb 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -309,6 +309,54 @@ def fullclean(action, args):
         else:
             os.remove(f)
 
+def print_closing_message(args):
+    # print a closing message of some kind
+    #
+
+    if "flash" in str(args.actions):
+        print("Done")
+        return
+
+    # Otherwise, if we built any binaries print a message about
+    # how to flash them
+    def print_flashing_message(title, key):
+        print("\n%s build complete. To flash, run this command:" % title)
+
+        with open(os.path.join(args.build_dir, "flasher_args.json")) as f:
+            flasher_args = json.load(f)
+
+        def flasher_path(f):
+            return os.path.relpath(os.path.join(args.build_dir, f))
+
+        if key != "project":
+            cmd = ""
+            if key == "bootloader":
+                cmd = " ".join(flasher_args["write_flash_args"]) + " "
+
+            cmd += flasher_args[key]["offset"] + " "
+            cmd += flasher_path(flasher_args[key]["file"])
+        else:
+            cmd = " ".join(flasher_args["write_flash_args"]) + " "
+            for o,f in flasher_args["flash_files"].items():
+                cmd += o + " " + flasher_path(f) + " "
+
+        print("%s -p %s -b %s write_flash %s" % (
+            os.path.relpath("%s/components/esptool_py/esptool/esptool.py" % os.environ["IDF_PATH"]),
+            args.port or "(PORT)",
+            args.baud,
+            cmd.strip()))
+        print("or run 'idf.py %s'" % (key + "-flash" if key != "project" else "flash",))
+
+    if "all" in args.actions or "build" in args.actions:
+        print_flashing_message("Project", "project")
+    else:
+        if "app" in args.actions:
+            print_flashing_message("App", "app")
+        if "partition_table" in args.actions:
+            print_flashing_message("Partition Table", "partition_table")
+        if "bootloader" in args.actions:
+            print_flashing_message("Bootloader", "bootloader")
+
 ACTIONS = {
     # action name : ( function (or alias), dependencies, order-only dependencies )
     "all" :                  ( build_target, [], [ "reconfigure", "menuconfig", "clean", "fullclean" ] ),
@@ -343,7 +391,6 @@ def get_commandline_options():
             result.append(a)
     return result
 
-
 def main():
     if sys.version_info[0] != 2 or sys.version_info[1] != 7:
         raise FatalError("ESP-IDF currently only supports Python 2.7, and this is Python %d.%d.%d. Search for 'Setting the Python Interpreter' in the ESP-IDF docs for some tips to handle this." % sys.version_info[:3])
@@ -394,10 +441,12 @@ def main():
 
         completed_actions.add(action)
 
-    while len(args.actions) > 0:
-        execute_action(args.actions[0], args.actions[1:])
-        args.actions.pop(0)
+    actions = list(args.actions)
+    while len(actions) > 0:
+        execute_action(actions[0], actions[1:])
+        actions.pop(0)
 
+    print_closing_message(args)
 
 if __name__ == "__main__":
     try:

From 2f433e4342e93aef3b66697e7216819c122d45fc Mon Sep 17 00:00:00 2001
From: Nicola Lunghi <25422924+nicola-lunghi@users.noreply.github.com>
Date: Thu, 24 May 2018 15:29:28 +0100
Subject: [PATCH 077/112] netif require vfs

---
 components/lwip/CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/lwip/CMakeLists.txt b/components/lwip/CMakeLists.txt
index d44424735..2d362f288 100644
--- a/components/lwip/CMakeLists.txt
+++ b/components/lwip/CMakeLists.txt
@@ -16,7 +16,7 @@ set(COMPONENT_SRCDIRS
     ${LWIP_PPP_DIRS} netif
     port/freertos port/netif port/debug port)
 
-set(COMPONENT_REQUIRES "")
+set(COMPONENT_REQUIRES vfs)
 set(COMPONENT_PRIV_REQUIRES ethernet tcpip_adapter)
 
 register_component()

From e100acbb731c03e46ea55272d53a919925af792d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 25 May 2018 16:22:18 +1000
Subject: [PATCH 078/112] docs: Minor cleanup of getting started docs

---
 .../establish-serial-connection.rst           |  2 +-
 docs/en/get-started/index.rst                 | 47 +++++++++----------
 docs/en/get-started/macos-setup.rst           |  7 +++
 3 files changed, 29 insertions(+), 27 deletions(-)

diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
index e7f8e9d96..ec8e4b1c5 100644
--- a/docs/en/get-started/establish-serial-connection.rst
+++ b/docs/en/get-started/establish-serial-connection.rst
@@ -71,7 +71,7 @@ Make sure you re-login to enable read and write permissions for the serial port.
 Verify serial connection
 ------------------------
 
-Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client <http://www.putty.org/>`_ that is avilable for both Windows and Linux. You can use other serial program and set communication parameters like below.
+Now verify that the serial connection is operational. You can do this using a serial terminal program. Windows and Linux users can use the `PuTTY SSH Client <http://www.putty.org/>`_ for this. Alternatively, any other serial program can be used with the communication parameters shown below.
 
 Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as  115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
 
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 8542bd37a..c99fc669f 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -2,7 +2,7 @@
 Get Started
 ***********
 
-This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
 
 .. note::
    The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
@@ -22,7 +22,8 @@ What You Need
 To develop applications for ESP32 you need:
 
 * **PC** loaded with either Windows, Linux or Mac operating system
-* **Toolchain** to build the **Application** for ESP32
+* **Toolchain** to compile code for ESP32
+* **Build tools** CMake and Ninja to build a full **Application** for ESP32
 * **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
 * A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
 * The **ESP32** board itself and a **USB cable** to connect it to the **PC**
@@ -34,28 +35,23 @@ To develop applications for ESP32 you need:
 
     Development of applications for ESP32
 
-Preparation of development environment consists of three steps:
+Development Environment Steps:
 
 1. Setup of **Toolchain**
-2. Getting of **ESP-IDF** from GitHub
-3. Installation and configuration of **Eclipse**
+2. Getting **ESP-IDF** from GitHub
 
-You may skip the last step, if you prefer to use different editor.
-
-Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
+Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
 
 1. Configuration of a **Project** and writing the code
 2. Compilation of the **Project** and linking it to build an **Application**
-3. Flashing (uploading) of the **Application** to **ESP32**
-4. Monitoring / debugging of the **Application**
-
-See instructions below that will walk you through these steps.
+3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
+4. Monitoring / debugging of the **Application** output via USB/serial
 
 
-Guides
-======
+Development Board Guides
+========================
 
-If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
+If you have one of ESP32 development boards listed below, click on the link for hardware setup:
 
 .. toctree::
     :maxdepth: 1
@@ -125,7 +121,7 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``.
 
 .. highlight:: batch
 
-For Windows Command Prompt users, the equivalent commands are::
+For **Windows Command Prompt** users, the equivalent commands are::
 
     mkdir %userprofile%\esp
     cd %userprofile%\esp
@@ -176,7 +172,7 @@ Copy :example:`get-started/hello_world` to ``~/esp`` directory::
 
 .. highlight:: batch
 
-For Windows Command Prompt users, the equivalent commands are::
+For **Windows Command Prompt** users, the equivalent commands are::
 
     cd %userprofile%\esp
     xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
@@ -187,7 +183,7 @@ It is also possible to build examples in-place, without copying them first.
 
 .. important::
 
-    The esp-idf build system does not support spaces in paths to esp-idf or to projects.
+    The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
 
 
 .. _get-started-connect:
@@ -197,7 +193,6 @@ Connect
 
 You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
 
-
 .. _get-started-configure:
 
 Configure
@@ -212,7 +207,7 @@ Being in terminal window, go to directory of ``hello_world`` application by typi
 
 .. highlight:: batch
 
-For Windows Command Prompt users::
+For **Windows Command Prompt** users::
 
     cd %userprofile%\esp\hello_world
     idf.py menuconfig
@@ -235,7 +230,7 @@ If previous steps have been done correctly, the following menu will be displayed
 Here are couple of tips on navigation and use of ``menuconfig``:
 
 * Use up & down arrow keys to navigate the menu.
-* Use Enter key to go into a submenu, Escape key to go out or to exit.
+* Use Enter key to go into a submenu, Escape key to go up a level or exit.
 * Type ``?`` to see a help screen. Enter key exits the help screen.
 * Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
 * Pressing ``?`` while highlighting a configuration item displays help about that item.
@@ -329,7 +324,7 @@ This step will flash the binaries that you just built to your ESP32 board.
 
 If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.
 
-If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
+.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
 
 
 .. _get-started-build-monitor:
@@ -369,7 +364,7 @@ To exit the monitor use shortcut ``Ctrl+]``.
         e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
         ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
 
-    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+    or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
 
 .. note::
 
@@ -401,7 +396,7 @@ Another solution is to update only what has changed. This method is useful if yo
 
 .. highlight:: batch
 
-For Windows Command Prompt users::
+For **Windows Command Prompt** users::
 
     cd %userprofile%\esp\esp-idf
     git pull
@@ -411,7 +406,7 @@ The ``git pull`` command is fetching and merging changes from ESP-IDF repository
 
 .. highlight:: bash
 
-If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
+To use a specific release of ESP-IDF, e.g. `v2.1`, run::
 
     cd ~/esp
     git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
@@ -421,7 +416,7 @@ If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
 
 .. highlight:: batch
 
-For Windows Command Prompt users::
+For **Windows Command Prompt** users::
 
     cd %userprofile%\esp
     git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst
index 70142482e..fc9ffc9b3 100644
--- a/docs/en/get-started/macos-setup.rst
+++ b/docs/en/get-started/macos-setup.rst
@@ -32,6 +32,13 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
 
 - It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
 
+.. note::
+   If an error like this is shown during any step::
+
+     xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
+
+    Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
+
 Toolchain Setup
 ===============
 

From 2909fc182b3671476b6eb6b52b62c0b2e5c10406 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 25 May 2018 16:24:29 +1000
Subject: [PATCH 079/112] esptool: Remove tabs from KConfig.projbuild

---
 components/esptool_py/Kconfig.projbuild | 126 ++++++++++++------------
 1 file changed, 63 insertions(+), 63 deletions(-)

diff --git a/components/esptool_py/Kconfig.projbuild b/components/esptool_py/Kconfig.projbuild
index e34d57759..799b576a0 100644
--- a/components/esptool_py/Kconfig.projbuild
+++ b/components/esptool_py/Kconfig.projbuild
@@ -1,10 +1,10 @@
 menu "Serial flasher config"
 
 config ESPTOOLPY_PORT
-	string "Default serial port"
+    string "Default serial port"
     depends on !IDF_CMAKE
-	default "/dev/ttyUSB0"
-	help
+    default "/dev/ttyUSB0"
+    help
         The serial port that's connected to the ESP chip. This can be overridden by setting the ESPPORT
         environment variable.
 
@@ -21,115 +21,115 @@ choice ESPTOOLPY_BAUD
         This value is ignored when using the CMake-based build system or idf.py.
 
 config ESPTOOLPY_BAUD_115200B
-	bool "115200 baud"
+    bool "115200 baud"
 config ESPTOOLPY_BAUD_230400B
-	bool "230400 baud"
+    bool "230400 baud"
 config ESPTOOLPY_BAUD_921600B
-	bool "921600 baud"
+    bool "921600 baud"
 config ESPTOOLPY_BAUD_2MB
-	bool "2Mbaud"
+    bool "2Mbaud"
 config ESPTOOLPY_BAUD_OTHER
     bool "Other baud rate"
 endchoice
 
 config ESPTOOLPY_BAUD_OTHER_VAL
-	int "Other baud rate value" if ESPTOOLPY_BAUD_OTHER
-	default 115200
+    int "Other baud rate value" if ESPTOOLPY_BAUD_OTHER
+    default 115200
 
 config ESPTOOLPY_BAUD
-	int
+    int
     depends on !IDF_CMAKE
-	default 115200 if ESPTOOLPY_BAUD_115200B
-	default 230400 if ESPTOOLPY_BAUD_230400B
-	default 921600 if ESPTOOLPY_BAUD_921600B
-	default 2000000 if ESPTOOLPY_BAUD_2MB
-	default ESPTOOLPY_BAUD_OTHER_VAL if ESPTOOLPY_BAUD_OTHER
+    default 115200 if ESPTOOLPY_BAUD_115200B
+    default 230400 if ESPTOOLPY_BAUD_230400B
+    default 921600 if ESPTOOLPY_BAUD_921600B
+    default 2000000 if ESPTOOLPY_BAUD_2MB
+    default ESPTOOLPY_BAUD_OTHER_VAL if ESPTOOLPY_BAUD_OTHER
 
 config ESPTOOLPY_COMPRESSED
-	bool "Use compressed upload"
+    bool "Use compressed upload"
     depends on !IDF_CMAKE
-	default "y"
-	help
-		The flasher tool can send data compressed using zlib, letting the ROM on the ESP chip
-		decompress it on the fly before flashing it. For most payloads, this should result in a
-		speed increase.
+    default "y"
+    help
+        The flasher tool can send data compressed using zlib, letting the ROM on the ESP chip
+        decompress it on the fly before flashing it. For most payloads, this should result in a
+        speed increase.
 
 choice FLASHMODE
-	prompt "Flash SPI mode"
-	default FLASHMODE_DIO
-	help
-		Mode the flash chip is flashed in, as well as the default mode for the
-		binary to run in.
+    prompt "Flash SPI mode"
+    default FLASHMODE_DIO
+    help
+        Mode the flash chip is flashed in, as well as the default mode for the
+        binary to run in.
 
 config FLASHMODE_QIO
-	bool "QIO"
+    bool "QIO"
 config FLASHMODE_QOUT
-	bool "QOUT"
+    bool "QOUT"
 config FLASHMODE_DIO
-	bool "DIO"
+    bool "DIO"
 config FLASHMODE_DOUT
-	bool "DOUT"
+    bool "DOUT"
 endchoice
 
 # Note: we use esptool.py to flash bootloader in
 # dio mode for QIO/QOUT, bootloader then upgrades
 # itself to quad mode during initialisation
 config ESPTOOLPY_FLASHMODE
-	string
-	default "dio" if FLASHMODE_QIO
-	default "dio" if FLASHMODE_QOUT
-	default "dio" if FLASHMODE_DIO
-	default "dout" if FLASHMODE_DOUT
+    string
+    default "dio" if FLASHMODE_QIO
+    default "dio" if FLASHMODE_QOUT
+    default "dio" if FLASHMODE_DIO
+    default "dout" if FLASHMODE_DOUT
 
 choice ESPTOOLPY_FLASHFREQ
-	prompt "Flash SPI speed"
-	default ESPTOOLPY_FLASHFREQ_40M
-	help
-		The SPI flash frequency to be used.
+    prompt "Flash SPI speed"
+    default ESPTOOLPY_FLASHFREQ_40M
+    help
+        The SPI flash frequency to be used.
 
 config ESPTOOLPY_FLASHFREQ_80M
-	bool "80 MHz"
+    bool "80 MHz"
 config ESPTOOLPY_FLASHFREQ_40M
-	bool "40 MHz"
+    bool "40 MHz"
 config ESPTOOLPY_FLASHFREQ_26M
-	bool "26 MHz"
+    bool "26 MHz"
 config ESPTOOLPY_FLASHFREQ_20M
-	bool "20 MHz"
+    bool "20 MHz"
 endchoice
 
 config ESPTOOLPY_FLASHFREQ
-	string
-	default "80m" if ESPTOOLPY_FLASHFREQ_80M
-	default "40m" if ESPTOOLPY_FLASHFREQ_40M
-	default "26m" if ESPTOOLPY_FLASHFREQ_26M
-	default "20m" if ESPTOOLPY_FLASHFREQ_20M
+    string
+    default "80m" if ESPTOOLPY_FLASHFREQ_80M
+    default "40m" if ESPTOOLPY_FLASHFREQ_40M
+    default "26m" if ESPTOOLPY_FLASHFREQ_26M
+    default "20m" if ESPTOOLPY_FLASHFREQ_20M
 
 
 choice ESPTOOLPY_FLASHSIZE
-	prompt "Flash size"
-	default ESPTOOLPY_FLASHSIZE_2MB
-	help
-		SPI flash size, in megabytes
+    prompt "Flash size"
+    default ESPTOOLPY_FLASHSIZE_2MB
+    help
+        SPI flash size, in megabytes
 
 config ESPTOOLPY_FLASHSIZE_1MB
-	bool "1 MB"
+    bool "1 MB"
 config ESPTOOLPY_FLASHSIZE_2MB
-	bool "2 MB"
+    bool "2 MB"
 config ESPTOOLPY_FLASHSIZE_4MB
-	bool "4 MB"
+    bool "4 MB"
 config ESPTOOLPY_FLASHSIZE_8MB
-	bool "8 MB"
+    bool "8 MB"
 config ESPTOOLPY_FLASHSIZE_16MB
-	bool "16 MB"
+    bool "16 MB"
 endchoice
 
 config ESPTOOLPY_FLASHSIZE
-	string
-	default "1MB" if ESPTOOLPY_FLASHSIZE_1MB
-	default "2MB" if ESPTOOLPY_FLASHSIZE_2MB
-	default "4MB" if ESPTOOLPY_FLASHSIZE_4MB
-	default "8MB" if ESPTOOLPY_FLASHSIZE_8MB
-	default "16MB" if ESPTOOLPY_FLASHSIZE_16MB
+    string
+    default "1MB" if ESPTOOLPY_FLASHSIZE_1MB
+    default "2MB" if ESPTOOLPY_FLASHSIZE_2MB
+    default "4MB" if ESPTOOLPY_FLASHSIZE_4MB
+    default "8MB" if ESPTOOLPY_FLASHSIZE_8MB
+    default "16MB" if ESPTOOLPY_FLASHSIZE_16MB
 
 config ESPTOOLPY_FLASHSIZE_DETECT
     bool "Detect flash size when flashing bootloader"

From c70f9db36912ea922677bfba147e30ccb26a6711 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 29 May 2018 11:10:30 +1000
Subject: [PATCH 080/112] confgen: Don't write environment-loaded configuration
 items to sdkconfig

---
 tools/kconfig_new/kconfiglib.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/kconfig_new/kconfiglib.py b/tools/kconfig_new/kconfiglib.py
index 527c5a55a..a8522a5c8 100644
--- a/tools/kconfig_new/kconfiglib.py
+++ b/tools/kconfig_new/kconfiglib.py
@@ -924,7 +924,7 @@ class Kconfig(object):
 
             def write_node(node):
                 item = node.item
-                if isinstance(item, Symbol):
+                if isinstance(item, Symbol) and item.env_var is None:
                     config_string = item.config_string
                     if config_string:
                         write(config_string)

From cfa8ed15c02adb5feaae3e4a52ed5f09f4dbd738 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 29 May 2018 14:46:45 +1000
Subject: [PATCH 081/112] partition table: Set partition table offset via
 variable

---
 components/esptool_py/flasher_args.json.in       | 4 ++--
 components/partition_table/CMakeLists.txt        | 4 +---
 components/partition_table/project_include.cmake | 1 +
 3 files changed, 4 insertions(+), 5 deletions(-)
 create mode 100644 components/partition_table/project_include.cmake

diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
index 55e3a93a5..1d68a2bb9 100644
--- a/components/esptool_py/flasher_args.json.in
+++ b/components/esptool_py/flasher_args.json.in
@@ -4,7 +4,7 @@
                            "--flash_freq", "${ESPFLASHFREQ}" ],
     "flash_files" : {
         "0x1000" : "bootloader/bootloader.bin",
-        "0x8000" : "partition_table/partition-table.bin",
+        "${PARTITION_TABLE_OFFSET}" : "partition_table/partition-table.bin",
         "${CONFIG_APP_OFFSET}" : "${PROJECT_NAME}.bin",
         "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}"
     },
@@ -12,6 +12,6 @@
                           "file" : "bootloader/bootloader.bin" },
     "app" :             { "offset" : "${CONFIG_APP_OFFSET}",
                           "file" : "${PROJECT_NAME}.bin" },
-    "partition_table" : { "offset" : "0x8000",
+    "partition_table" : { "offset" : "${PARTITION_TABLE_OFFSET}",
                           "file" : "partition_table/partition-table.bin" }
 }
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index 72ef78ff1..eae14ceb2 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -1,5 +1,3 @@
-set(partition_table_offset 0x8000)
-
 register_config_only_component()
 
 # Set partition_csv to the configured partition source file
@@ -56,5 +54,5 @@ add_custom_target(partition_table ALL DEPENDS "${final_partition_bin}")
 # the list of esptool write arguments for flashing
 set_property(GLOBAL APPEND_STRING PROPERTY
     ESPTOOL_WRITE_FLASH_ARGS
-    "${partition_table_offset} ${final_partition_bin} ")
+    "${PARTITION_TABLE_OFFSET} ${final_partition_bin} ")
 
diff --git a/components/partition_table/project_include.cmake b/components/partition_table/project_include.cmake
new file mode 100644
index 000000000..1658df30e
--- /dev/null
+++ b/components/partition_table/project_include.cmake
@@ -0,0 +1 @@
+set(PARTITION_TABLE_OFFSET 0x8000)

From fdccc19485e160c159e8dd0d51b517412906c93d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 31 May 2018 13:31:42 +1000
Subject: [PATCH 082/112] cmake build system test: Fix path to sdkconfig.h

---
 tools/ci/test_build_system_cmake.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh
index 8484255a0..ed2baf23a 100755
--- a/tools/ci/test_build_system_cmake.sh
+++ b/tools/ci/test_build_system_cmake.sh
@@ -159,7 +159,7 @@ function run_tests()
     sed -i s/CONFIG_FREERTOS_UNICORE=/CONFIG_FREERTOS_UNICORE=y/ sdkconfig
     idf.py build
     # check the sdkconfig.h file was rebuilt
-    assert_rebuilt sdkconfig.h
+    assert_rebuilt config/sdkconfig.h
     # pick one each of .c, .cpp, .S that #includes sdkconfig.h
     # and therefore should rebuild
     assert_rebuilt newlib/CMakeFiles/newlib.dir/syscall_table.c.obj

From 8bb4c694cef2c011a52581c378031d5a5ce28621 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 30 May 2018 17:55:44 +1000
Subject: [PATCH 083/112] cmake: Add COMPONENT_SRCEXCLUDE option

---
 docs/en/api-guides/build-system.rst |  2 ++
 tools/cmake/components.cmake        | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index f32cc9eb3..01235fa08 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -323,6 +323,7 @@ The following variables can be set inside ``component.mk`` to control the build
   ``*.c``, ``*.S``). Set this to specify a list of directories which contain source files.
 - ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
   If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``.
+- ``COMPONENT_SRCEXCLUDE``: Paths to source files to exclude from component. Can be set in conjunction with ``COMPONENT_SRCDIRS`` if there is a directory with a large number of source files to include in the component but one or more source files which should not be. Paths can be specified relative to the component directory or absolute.
 
 Controlling Component Compilation
 ---------------------------------
@@ -835,6 +836,7 @@ Some features are significantly different or removed in the CMake-based system.
 - ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repo.
 - ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
 - ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``.
+- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead.
 - ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
 - ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
 - ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index 506d8a06f..fc7c7f5ed 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -20,6 +20,7 @@ function(register_component)
 
     spaces2list(COMPONENT_SRCDIRS)
     spaces2list(COMPONENT_ADD_INCLUDEDIRS)
+    spaces2list(COMPONENT_SRCEXCLUDE)
 
     # Add to COMPONENT_SRCS by globbing in COMPONENT_SRCDIRS
     if(NOT COMPONENT_SRCS)
@@ -39,6 +40,17 @@ function(register_component)
         endforeach()
     endif()
 
+    # Remove COMPONENT_SRCEXCLUDE matches
+    foreach(exclude ${COMPONENT_SRCEXCLUDE})
+        get_filename_component(exclude "${exclude}" ABSOLUTE ${component_dir})
+        foreach(src ${COMPONENT_SRCS})
+            get_filename_component(abs_src "${src}" ABSOLUTE ${component_dir})
+            if("${exclude}" STREQUAL "${abs_src}")  # compare as canonical paths
+                list(REMOVE_ITEM COMPONENT_SRCS src)
+            endif()
+        endforeach()
+    endforeach()
+
     # add as a PUBLIC library (if there are source files) or INTERFACE (if header only)
     if(COMPONENT_SRCS OR embed_binaries)
         add_library(${component} STATIC ${COMPONENT_SRCS})

From 4667fb2495929465238d47060a7247f7996e76cb Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 6 Jun 2018 16:14:03 +1000
Subject: [PATCH 084/112] cmake: Compatibility fixes from Mahavir

---
 components/nghttp/CMakeLists.txt         | 2 --
 components/pthread/CMakeLists.txt        | 4 ++++
 components/wpa_supplicant/CMakeLists.txt | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/components/nghttp/CMakeLists.txt b/components/nghttp/CMakeLists.txt
index bf3f72746..c7e4b754b 100644
--- a/components/nghttp/CMakeLists.txt
+++ b/components/nghttp/CMakeLists.txt
@@ -1,6 +1,4 @@
 set(COMPONENT_ADD_INCLUDEDIRS port/include nghttp2/lib/includes)
 set(COMPONENT_SRCDIRS nghttp2/lib port)
 
-set(COMPONENT_REQUIRES lwip mbedtls)
-
 register_component()
diff --git a/components/pthread/CMakeLists.txt b/components/pthread/CMakeLists.txt
index ad162fe1e..0b93e09ed 100644
--- a/components/pthread/CMakeLists.txt
+++ b/components/pthread/CMakeLists.txt
@@ -2,3 +2,7 @@ set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 set(COMPONENT_REQUIRES)
 register_component()
+
+if(CONFIG_ENABLE_STATIC_TASK_CLEAN_UP_HOOK)
+    target_link_libraries(pthread "-Wl,--wrap=vPortCleanUpTCB")
+endif()
diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
index d349e96be..e77e3160b 100644
--- a/components/wpa_supplicant/CMakeLists.txt
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -2,7 +2,7 @@ set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto)
 set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 
 set(COMPONENT_REQUIRES "")
-set(COMPONENT_PRIV_REQUIRES lwip mbedtls)
+set(COMPONENT_PRIV_REQUIRES mbedtls)
 
 register_component()
 

From 46b723e5edb129bcfaa3e6df85be2f7dfb55ea83 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 6 Jun 2018 16:27:44 +1000
Subject: [PATCH 085/112] cmake: Fix COMPONENT_SRCEXCLUDE functionality

---
 tools/cmake/components.cmake | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/cmake/components.cmake b/tools/cmake/components.cmake
index fc7c7f5ed..0056a3b4a 100644
--- a/tools/cmake/components.cmake
+++ b/tools/cmake/components.cmake
@@ -46,7 +46,7 @@ function(register_component)
         foreach(src ${COMPONENT_SRCS})
             get_filename_component(abs_src "${src}" ABSOLUTE ${component_dir})
             if("${exclude}" STREQUAL "${abs_src}")  # compare as canonical paths
-                list(REMOVE_ITEM COMPONENT_SRCS src)
+                list(REMOVE_ITEM COMPONENT_SRCS "${src}")
             endif()
         endforeach()
     endforeach()

From 6065d2fd089267e9bb79bc5734f9ede4af3f8d63 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 16 May 2018 14:54:22 +0800
Subject: [PATCH 086/112] kconfig: Add confserver.py to expose sdkconfig to
 clients

---
 .gitlab-ci.yml                            |   9 ++
 docs/en/api-guides/build-system.rst       |  57 ++++++-
 tools/ci/executable-list.txt              |   2 +
 tools/cmake/kconfig.cmake                 |  11 ++
 tools/idf.py                              |   1 +
 tools/kconfig_new/confgen.py              |  92 ++++++++++-
 tools/kconfig_new/confserver.py           | 185 ++++++++++++++++++++++
 tools/kconfig_new/kconfiglib.py           |  41 +++--
 tools/kconfig_new/test/Kconfig            |  44 +++++
 tools/kconfig_new/test/sdkconfig          |   1 +
 tools/kconfig_new/test/test_confserver.py | 114 +++++++++++++
 tools/kconfig_new/test/testcases.txt      |  31 ++++
 12 files changed, 568 insertions(+), 20 deletions(-)
 create mode 100755 tools/kconfig_new/confserver.py
 create mode 100644 tools/kconfig_new/test/Kconfig
 create mode 100644 tools/kconfig_new/test/sdkconfig
 create mode 100755 tools/kconfig_new/test/test_confserver.py
 create mode 100644 tools/kconfig_new/test/testcases.txt

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 3b8c9dabe..ff1604c5e 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -306,6 +306,15 @@ test_multi_heap_on_host:
     - cd components/heap/test_multi_heap_host
     - ./test_all_configs.sh
 
+test_confserver:
+  stage: test
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
+  tags:
+    - confserver_test
+  script:
+    - cd tools/kconfig_new/test
+    - ./test_confserver.py
+
 test_build_system:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index 01235fa08..f1055afd9 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -130,6 +130,8 @@ You can also use an IDE with CMake integration. The IDE will want to know the pa
 
 When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
 
+For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_.
+
 .. setting-python-interpreter:
 
 Setting the Python Interpreter
@@ -781,13 +783,65 @@ The best option will depend on your particular project and its users.
 Build System Metadata
 =====================
 
-For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
 
 - ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
 - ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
 - ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
 - ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
 - ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
+- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs.
+
+JSON Configuration Server
+-------------------------
+
+.. highlight :: json
+
+A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
+
+You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator.
+
+The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``::
+
+  {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
+
+Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.)
+
+The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline::
+
+   {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
+
+The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes::
+
+   {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
+
+Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value.
+
+If the range of a config item changes, due to conditional range depending on another value, then this is also sent::
+
+   {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
+
+If invalid data is passed, an "error" field is present on the object::
+
+    {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
+
+By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent::
+
+    {"version": 1, "save": null }
+
+To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent::
+
+    {"version": 1, "load": null }
+
+The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname.
+
+The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started.
+
+Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command.
+
+.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited.
+
+.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run.
 
 .. _gnu-make-to-cmake:
 
@@ -856,6 +910,7 @@ No Longer Necessary
 
 It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
 
+
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _cmake: https://cmake.org
 .. _ninja: https://ninja-build.org
diff --git a/tools/ci/executable-list.txt b/tools/ci/executable-list.txt
index 78115cdc8..a800ab83b 100644
--- a/tools/ci/executable-list.txt
+++ b/tools/ci/executable-list.txt
@@ -37,4 +37,6 @@ tools/cmake/convert_to_cmake.py
 tools/cmake/run_cmake_lint.sh
 tools/idf.py
 tools/kconfig_new/confgen.py
+tools/kconfig_new/confserver.py
+tools/kconfig_new/test/test_confserver.py
 tools/windows/tool_setup/build_installer.sh
diff --git a/tools/cmake/kconfig.cmake b/tools/cmake/kconfig.cmake
index 478b73e34..040103575 100644
--- a/tools/cmake/kconfig.cmake
+++ b/tools/cmake/kconfig.cmake
@@ -6,6 +6,7 @@ macro(kconfig_set_variables)
     set(SDKCONFIG_HEADER ${CONFIG_DIR}/sdkconfig.h)
     set(SDKCONFIG_CMAKE ${CONFIG_DIR}/sdkconfig.cmake)
     set(SDKCONFIG_JSON ${CONFIG_DIR}/sdkconfig.json)
+    set(KCONFIG_JSON_MENUS ${CONFIG_DIR}/kconfig_menus.json)
 
     set(ROOT_KCONFIG ${IDF_PATH}/Kconfig)
 
@@ -123,6 +124,15 @@ function(kconfig_process_config)
         VERBATIM
         USES_TERMINAL)
 
+    # Custom target to run confserver.py from the build tool
+    add_custom_target(confserver
+        COMMAND ${CMAKE_COMMAND} -E env
+        "COMPONENT_KCONFIGS=${kconfigs}"
+        "COMPONENT_KCONFIGS_PROJBUILD=${kconfigs_projbuild}"
+        ${IDF_PATH}/tools/kconfig_new/confserver.py --kconfig ${IDF_PATH}/Kconfig --config ${SDKCONFIG}
+        VERBATIM
+        USES_TERMINAL)
+
     # Generate configuration output via confgen.py
     # makes sdkconfig.h and skdconfig.cmake
     #
@@ -131,6 +141,7 @@ function(kconfig_process_config)
         --output header ${SDKCONFIG_HEADER}
         --output cmake ${SDKCONFIG_CMAKE}
         --output json ${SDKCONFIG_JSON}
+        --output json_menus ${KCONFIG_JSON_MENUS}
         RESULT_VARIABLE config_result)
     if(config_result)
         message(FATAL_ERROR "Failed to run confgen.py (${confgen_basecommand}). Error ${config_result}")
diff --git a/tools/idf.py b/tools/idf.py
index 8b2c058fb..402d334bb 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -365,6 +365,7 @@ ACTIONS = {
     "fullclean":             ( fullclean,    [], [] ),
     "reconfigure":           ( reconfigure,  [], [ "menuconfig" ] ),
     "menuconfig":            ( build_target, [], [] ),
+    "confserver":            ( build_target, [], [] ),
     "size":                  ( build_target, [ "app" ], [] ),
     "size-components":       ( build_target, [ "app" ], [] ),
     "size-files":            ( build_target, [ "app" ], [] ),
diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
index 13c741505..b78967d48 100755
--- a/tools/kconfig_new/confgen.py
+++ b/tools/kconfig_new/confgen.py
@@ -29,6 +29,7 @@ import json
 
 import gen_kconfig_doc
 import kconfiglib
+import pprint
 
 __version__ = "0.1"
 
@@ -65,7 +66,7 @@ def main():
 
     for fmt, filename in args.output:
         if not fmt in OUTPUT_FORMATS.keys():
-            print("Format '%s' not recognised. Known formats: %s" % (fmt, OUTPUT_FORMATS))
+            print("Format '%s' not recognised. Known formats: %s" % (fmt, OUTPUT_FORMATS.keys()))
             sys.exit(1)
 
     try:
@@ -150,9 +151,8 @@ def write_cmake(config, filename):
                     prefix, sym.name, val))
         config.walk_menu(write_node)
 
-def write_json(config, filename):
+def get_json_values(config):
     config_dict = {}
-
     def write_node(node):
         sym = node.item
         if not isinstance(sym, kconfiglib.Symbol):
@@ -168,9 +168,94 @@ def write_json(config, filename):
                 val = int(val)
             config_dict[sym.name] = val
     config.walk_menu(write_node)
+    return config_dict
+
+def write_json(config, filename):
+    config_dict = get_json_values(config)
     with open(filename, "w") as f:
         json.dump(config_dict, f, indent=4, sort_keys=True)
 
+def write_json_menus(config, filename):
+    result = []  # root level items
+    node_lookup = {}  # lookup from MenuNode to an item in result
+
+    def write_node(node):
+        try:
+            json_parent = node_lookup[node.parent]["children"]
+        except KeyError:
+            assert not node.parent in node_lookup  # if fails, we have a parent node with no "children" entity (ie a bug)
+            json_parent = result  # root level node
+
+        # node.kconfig.y means node has no dependency,
+        if node.dep is node.kconfig.y:
+            depends = None
+        else:
+            depends = kconfiglib.expr_str(node.dep)
+
+        try:
+            is_menuconfig = node.is_menuconfig
+        except AttributeError:
+            is_menuconfig = False
+
+        new_json = None
+        if node.item == kconfiglib.MENU or is_menuconfig:
+            new_json = { "type" : "menu",
+                         "title" : node.prompt[0],
+                         "depends_on": depends,
+                         "children": []
+            }
+            if is_menuconfig:
+                sym = node.item
+                new_json["name"] = sym.name
+                new_json["help"] = node.help
+                new_json["is_menuconfig"] = is_menuconfig
+                greatest_range = None
+                if len(sym.ranges) > 0:
+                    # Note: Evaluating the condition using kconfiglib's expr_value
+                    # should have one result different from value 0 ("n").
+                    for min_range, max_range, cond_expr in sym.ranges:
+                        if kconfiglib.expr_value(cond_expr) != "n":
+                            greatest_range = [min_range, max_range]
+                new_json["range"] = greatest_range
+
+        elif isinstance(node.item, kconfiglib.Symbol):
+            sym = node.item
+            greatest_range = None
+            if len(sym.ranges) > 0:
+                # Note: Evaluating the condition using kconfiglib's expr_value
+                # should have one result different from value 0 ("n").
+                for min_range, max_range, cond_expr in sym.ranges:
+                    if kconfiglib.expr_value(cond_expr) != "n":
+                        greatest_range = [int(min_range.str_value), int(max_range.str_value)]
+
+            new_json = {
+                "type" : kconfiglib.TYPE_TO_STR[sym.type],
+                "name" : sym.name,
+                "title": node.prompt[0] if node.prompt else None,
+                "depends_on" : depends,
+                "help": node.help,
+                "range" : greatest_range,
+                "children": [],
+            }
+        elif isinstance(node.item, kconfiglib.Choice):
+            choice = node.item
+            new_json = {
+                "type": "choice",
+                "title": node.prompt[0],
+                "name": choice.name,
+                "depends_on" : depends,
+                "help": node.help,
+                "children": []
+            }
+
+        if new_json:
+            json_parent.append(new_json)
+            node_lookup[node] = new_json
+
+    config.walk_menu(write_node)
+    with open(filename, "w") as f:
+        f.write(json.dumps(result, sort_keys=True, indent=4))
+
 def update_if_changed(source, destination):
     with open(source, "r") as f:
         source_contents = f.read()
@@ -190,6 +275,7 @@ OUTPUT_FORMATS = {
     "cmake" : write_cmake,
     "docs" : gen_kconfig_doc.write_docs,
     "json" : write_json,
+    "json_menus" : write_json_menus,
     }
 
 class FatalError(RuntimeError):
diff --git a/tools/kconfig_new/confserver.py b/tools/kconfig_new/confserver.py
new file mode 100755
index 000000000..cf63a598d
--- /dev/null
+++ b/tools/kconfig_new/confserver.py
@@ -0,0 +1,185 @@
+#!/usr/bin/env python
+#
+# Long-running server process uses stdin & stdout to communicate JSON
+# with a caller
+#
+from __future__ import print_function
+import argparse
+import json
+import kconfiglib
+import os
+import sys
+import confgen
+from confgen import FatalError, __version__
+
+def main():
+    parser = argparse.ArgumentParser(description='confserver.py v%s - Config Generation Tool' % __version__, prog=os.path.basename(sys.argv[0]))
+
+    parser.add_argument('--config',
+                       help='Project configuration settings',
+                       required=True)
+
+    parser.add_argument('--kconfig',
+                        help='KConfig file with config item definitions',
+                        required=True)
+
+    parser.add_argument('--env', action='append', default=[],
+                        help='Environment to set when evaluating the config file', metavar='NAME=VAL')
+
+    args = parser.parse_args()
+
+    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
+
+    print("Server running, waiting for requests on stdin...", file=sys.stderr)
+    run_server(args.kconfig, args.config)
+
+
+def run_server(kconfig, sdkconfig):
+    config = kconfiglib.Kconfig(kconfig)
+    config.load_config(sdkconfig)
+
+    config_dict = confgen.get_json_values(config)
+    ranges_dict = get_ranges(config)
+    json.dump({"version": 1, "values" : config_dict, "ranges" : ranges_dict}, sys.stdout)
+    print("\n")
+
+    while True:
+        line = sys.stdin.readline()
+        if not line:
+            break
+        req = json.loads(line)
+        before = confgen.get_json_values(config)
+        before_ranges = get_ranges(config)
+
+        if "load" in req:  # if we're loading a different sdkconfig, response should have all items in it
+            before = {}
+            before_ranges = {}
+
+            # if no new filename is supplied, use existing sdkconfig path, otherwise update the path
+            if req["load"] is None:
+                req["load"] = sdkconfig
+            else:
+                sdkconfig = req["load"]
+
+        if "save" in req:
+            if req["save"] is None:
+                req["save"] = sdkconfig
+            else:
+                sdkconfig = req["save"]
+
+        error = handle_request(config, req)
+
+        after = confgen.get_json_values(config)
+        after_ranges = get_ranges(config)
+
+        values_diff = diff(before, after)
+        ranges_diff = diff(before_ranges, after_ranges)
+        response = {"version" : 1, "values" : values_diff, "ranges" : ranges_diff}
+        if error:
+            for e in error:
+                print("Error: %s" % e, file=sys.stderr)
+            response["error"] = error
+        json.dump(response, sys.stdout)
+        print("\n")
+
+
+def handle_request(config, req):
+    if not "version" in req:
+        return [ "All requests must have a 'version'" ]
+    if int(req["version"]) != 1:
+        return [ "Only version 1 requests supported" ]
+
+    error = []
+
+    if "load" in req:
+        print("Loading config from %s..." % req["load"], file=sys.stderr)
+        try:
+            config.load_config(req["load"])
+        except Exception as e:
+            error += [ "Failed to load from %s: %s" % (req["load"], e) ]
+
+    if "set" in req:
+        handle_set(config, error, req["set"])
+
+    if "save" in req:
+        try:
+            print("Saving config to %s..." % req["save"], file=sys.stderr)
+            confgen.write_config(config, req["save"])
+        except Exception as e:
+            error += [ "Failed to save to %s: %s" % (req["save"], e) ]
+
+    return error
+
+def handle_set(config, error, to_set):
+    missing = [ k for k in to_set if not k in config.syms ]
+    if missing:
+        error.append("The following config symbol(s) were not found: %s" % (", ".join(missing)))
+    # replace name keys with the full config symbol for each key:
+    to_set = dict((config.syms[k],v) for (k,v) in to_set.items() if not k in missing)
+
+    # Work through the list of values to set, noting that
+    # some may not be immediately applicable (maybe they depend
+    # on another value which is being set). Therefore, defer
+    # knowing if any value is unsettable until then end
+
+    while len(to_set):
+        set_pass = [ (k,v) for (k,v) in to_set.items() if k.visibility ]
+        if not set_pass:
+            break  # no visible keys left
+        for (sym,val) in set_pass:
+            if sym.type in (kconfiglib.BOOL, kconfiglib.TRISTATE):
+                if val == True:
+                    sym.set_value(2)
+                elif val == False:
+                    sym.set_value(0)
+                else:
+                    error.append("Boolean symbol %s only accepts true/false values" % sym.name)
+            else:
+                sym.set_value(str(val))
+            print("Set %s" % sym.name)
+            del to_set[sym]
+
+    if len(to_set):
+        error.append("The following config symbol(s) were not visible so were not updated: %s" % (", ".join(s.name for s in to_set)))
+
+
+
+def diff(before, after):
+    """
+    Return a dictionary with the difference between 'before' and 'after' (either with the new value if changed,
+    or None as the value if a key in 'before' is missing in 'after'
+    """
+    diff = dict((k,v) for (k,v) in after.items() if before.get(k, None) != v)
+    hidden = dict((k,None) for k in before if k not in after)
+    diff.update(hidden)
+    return diff
+
+
+def get_ranges(config):
+    ranges_dict = {}
+    def handle_node(node):
+        sym = node.item
+        if not isinstance(sym, kconfiglib.Symbol):
+            return
+        active_range = sym.active_range
+        if active_range[0] is not None:
+            ranges_dict[sym.name] = active_range
+
+    config.walk_menu(handle_node)
+    return ranges_dict
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except FatalError as e:
+        print("A fatal error occurred: %s" % e, file=sys.stderr)
+        sys.exit(2)
+
diff --git a/tools/kconfig_new/kconfiglib.py b/tools/kconfig_new/kconfiglib.py
index a8522a5c8..261e72e6b 100644
--- a/tools/kconfig_new/kconfiglib.py
+++ b/tools/kconfig_new/kconfiglib.py
@@ -2419,24 +2419,11 @@ class Symbol(object):
             base = _TYPE_TO_BASE[self.orig_type]
 
             # Check if a range is in effect
-            for low_expr, high_expr, cond in self.ranges:
-                if expr_value(cond):
-                    has_active_range = True
-
-                    # The zeros are from the C implementation running strtoll()
-                    # on empty strings
-                    low = int(low_expr.str_value, base) if \
-                      _is_base_n(low_expr.str_value, base) else 0
-                    high = int(high_expr.str_value, base) if \
-                      _is_base_n(high_expr.str_value, base) else 0
-
-                    break
-            else:
-                has_active_range = False
+            low, high = self.active_range
 
             if vis and self.user_value is not None and \
                _is_base_n(self.user_value, base) and \
-               (not has_active_range or
+               (low is None or
                 low <= int(self.user_value, base) <= high):
 
                 # If the user value is well-formed and satisfies range
@@ -2463,7 +2450,7 @@ class Symbol(object):
                     val_num = 0  # strtoll() on empty string
 
                 # This clamping procedure runs even if there's no default
-                if has_active_range:
+                if low is not None:
                     clamp = None
                     if val_num < low:
                         clamp = low
@@ -2714,6 +2701,28 @@ class Symbol(object):
             if self._is_user_assignable():
                 self._rec_invalidate()
 
+    @property
+    def active_range(self):
+        """
+        Returns a tuple of (low, high) integer values if a range
+        limit is active for this symbol, or (None, None) if no range
+        limit exists.
+        """
+        base = _TYPE_TO_BASE[self.orig_type]
+
+        for low_expr, high_expr, cond in self.ranges:
+            if expr_value(cond):
+                # The zeros are from the C implementation running strtoll()
+                # on empty strings
+                low = int(low_expr.str_value, base) if \
+                    _is_base_n(low_expr.str_value, base) else 0
+                high = int(high_expr.str_value, base) if \
+                    _is_base_n(high_expr.str_value, base) else 0
+
+                return (low, high)
+        return (None, None)
+
+
     def __repr__(self):
         """
         Returns a string with information about the symbol (including its name,
diff --git a/tools/kconfig_new/test/Kconfig b/tools/kconfig_new/test/Kconfig
new file mode 100644
index 000000000..958226749
--- /dev/null
+++ b/tools/kconfig_new/test/Kconfig
@@ -0,0 +1,44 @@
+menu "Test config"
+
+config TEST_BOOL
+  bool "Test boolean"
+  default n
+
+config TEST_CHILD_BOOL
+  bool "Test boolean"
+  depends on TEST_BOOL
+  default y
+
+config TEST_CHILD_STR
+  string "Test str"
+  depends on TEST_BOOL
+  default "OHAI!"
+
+choice TEST_CHOICE
+  prompt "Some choice"
+  default CHOICE_A
+
+config CHOICE_A
+  bool "A"
+
+config CHOICE_B
+  bool "B"
+
+endchoice
+
+config DEPENDS_ON_CHOICE
+   string "Depends on choice"
+   default "Depends on A" if CHOICE_A
+   default "Depends on B" if CHOICE_B
+   default "WAT"
+
+config SOME_UNRELATED_THING
+   bool "Some unrelated thing"
+
+config TEST_CONDITIONAL_RANGES
+   int "Something with a range"
+   range 0 100 if TEST_BOOL
+   range 0 10
+   default 1
+
+endmenu
diff --git a/tools/kconfig_new/test/sdkconfig b/tools/kconfig_new/test/sdkconfig
new file mode 100644
index 000000000..3f64ef10a
--- /dev/null
+++ b/tools/kconfig_new/test/sdkconfig
@@ -0,0 +1 @@
+CONFIG_SOME_UNRELATED_THING=y
diff --git a/tools/kconfig_new/test/test_confserver.py b/tools/kconfig_new/test/test_confserver.py
new file mode 100755
index 000000000..3ce25158b
--- /dev/null
+++ b/tools/kconfig_new/test/test_confserver.py
@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+import os
+import sys
+import threading
+import time
+import json
+import argparse
+import shutil
+
+import pexpect
+
+sys.path.append("..")
+import confserver
+
+def create_server_thread(*args):
+    t = threading.Thread()
+
+def parse_testcases():
+    with open("testcases.txt", "r") as f:
+        cases = [ l for l in f.readlines() if len(l.strip()) > 0 ]
+    # Each 3 lines in the file should be formatted as:
+    # * Description of the test change
+    # * JSON "changes" to send to the server
+    # * Result JSON to expect back from the server
+    if len(cases) % 3 != 0:
+        print("Warning: testcases.txt has wrong number of non-empty lines (%d). Should be 3 lines per test case, always." % len(cases))
+
+    for i in range(0, len(cases), 3):
+        desc = cases[i]
+        send = cases[i+1]
+        expect = cases[i+2]
+        if not desc.startswith("* "):
+            raise RuntimeError("Unexpected description at line %d: '%s'" % (i+1, desc))
+        if not send.startswith("> "):
+            raise RuntimeError("Unexpected send at line %d: '%s'" % (i+2, send))
+        if not expect.startswith("< "):
+            raise RuntimeError("Unexpected expect at line %d: '%s'" % (i+3, expect))
+        desc = desc[2:]
+        send = json.loads(send[2:])
+        expect = json.loads(expect[2:])
+        yield (desc, send, expect)
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--logfile', type=argparse.FileType('w'), help='Optional session log of the interactions with confserver.py')
+    args = parser.parse_args()
+
+    # set up temporary file to use as sdkconfig copy
+    temp_sdkconfig_path = os.tmpnam()
+    try:
+        with open(temp_sdkconfig_path, "w") as temp_sdkconfig:
+            with open("sdkconfig") as orig:
+                temp_sdkconfig.write(orig.read())
+
+        cmdline = "../confserver.py --kconfig Kconfig --config %s" % temp_sdkconfig_path
+        print("Running: %s" % cmdline)
+        p = pexpect.spawn(cmdline, timeout=0.5)
+        p.logfile = args.logfile
+        p.setecho(False)
+
+        def expect_json():
+            # run p.expect() to expect a json object back, and return it as parsed JSON
+            p.expect("{.+}\r\n")
+            return json.loads(p.match.group(0).strip())
+
+        p.expect("Server running.+\r\n")
+        initial = expect_json()
+        print("Initial: %s" % initial)
+        cases = parse_testcases()
+
+        for (desc, send, expected) in cases:
+            print(desc)
+            req = { "version" : "1", "set" : send }
+            req = json.dumps(req)
+            print("Sending: %s" % (req))
+            p.send("%s\n" % req)
+            readback = expect_json()
+            print("Read back: %s" % (json.dumps(readback)))
+            if readback.get("version", None) != 1:
+                raise RuntimeError('Expected {"version" : 1} in response')
+            for expect_key in expected.keys():
+                read_vals = readback[expect_key]
+                exp_vals = expected[expect_key]
+                if read_vals != exp_vals:
+                    expect_diff = dict((k,v) for (k,v) in exp_vals.items() if not k in read_vals or v != read_vals[k])
+                    raise RuntimeError("Test failed! Was expecting %s: %s" % (expect_key, json.dumps(expect_diff)))
+            print("OK")
+
+        print("Testing load/save...")
+        before = os.stat(temp_sdkconfig_path).st_mtime
+        p.send("%s\n" % json.dumps({ "version" : "1", "save" : temp_sdkconfig_path }))
+        save_result = expect_json()
+        print("Save result: %s" % (json.dumps(save_result)))
+        assert len(save_result["values"]) == 0
+        assert len(save_result["ranges"]) == 0
+        after = os.stat(temp_sdkconfig_path).st_mtime
+        assert after > before
+
+        p.send("%s\n" % json.dumps({ "version" : "1", "load" : temp_sdkconfig_path }))
+        load_result = expect_json()
+        print("Load result: %s" % (json.dumps(load_result)))
+        assert len(load_result["values"]) > 0  # loading same file should return all config items
+        assert len(load_result["ranges"]) > 0
+        print("Done. All passed.")
+
+    finally:
+        try:
+            os.remove(temp_sdkconfig_path)
+        except OSError:
+            pass
+
+if __name__ == "__main__":
+    main()
+
diff --git a/tools/kconfig_new/test/testcases.txt b/tools/kconfig_new/test/testcases.txt
new file mode 100644
index 000000000..4563d4928
--- /dev/null
+++ b/tools/kconfig_new/test/testcases.txt
@@ -0,0 +1,31 @@
+* Set TEST_BOOL, showing child items
+> { "TEST_BOOL" : true }
+< { "values" : { "TEST_BOOL" : true, "TEST_CHILD_STR" : "OHAI!", "TEST_CHILD_BOOL" : true }, "ranges": {"TEST_CONDITIONAL_RANGES": [0, 100]} }
+
+* Set TEST_CHILD_STR
+> { "TEST_CHILD_STR" : "Other value" }
+< { "values" : { "TEST_CHILD_STR" : "Other value" } }
+
+* Clear TEST_BOOL, hiding child items
+> { "TEST_BOOL" : false }
+< { "values" : { "TEST_BOOL" : false, "TEST_CHILD_STR" : null, "TEST_CHILD_BOOL" : null },  "ranges": {"TEST_CONDITIONAL_RANGES": [0, 10]} }
+
+* Set TEST_CHILD_BOOL, invalid as parent is disabled
+> { "TEST_CHILD_BOOL" : false }
+< { "values" : { } }
+
+* Set TEST_BOOL & TEST_CHILD_STR together
+> { "TEST_BOOL" : true, "TEST_CHILD_STR" : "New value" }
+< { "values" : { "TEST_BOOL" : true, "TEST_CHILD_STR" : "New value", "TEST_CHILD_BOOL" : true } }
+
+* Set choice
+> { "CHOICE_B" : true }
+< { "values" : { "CHOICE_B" : true, "CHOICE_A" : false, "DEPENDS_ON_CHOICE" : "Depends on B" } }
+
+* Set string which depends on choice B
+> { "DEPENDS_ON_CHOICE" : "oh, really?" }
+< { "values" : { "DEPENDS_ON_CHOICE" : "oh, really?" } }
+
+* Try setting boolean values to invalid types
+> { "CHOICE_A" : 11, "TEST_BOOL" : "false" }
+< { "values" : { } }

From 330c6a50e10b689cd19d8a5520b170b4627e1eef Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 6 Jun 2018 17:18:52 +1000
Subject: [PATCH 087/112] ci: Use new host_test tag

---
 .gitlab-ci.yml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index ff1604c5e..0f4d9d16b 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -250,7 +250,7 @@ test_nvs_on_host:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - nvs_host_test
+    - host_test
   dependencies: []
   script:
     - cd components/nvs_flash/test_nvs_host
@@ -260,7 +260,7 @@ test_nvs_coverage:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - nvs_host_test
+    - host_test
   dependencies: []
   artifacts:
     paths:
@@ -288,7 +288,7 @@ test_wl_on_host:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - wl_host_test
+    - host_test
   artifacts:
     paths:
       - components/wear_levelling/test_wl_host/coverage_report.zip
@@ -301,7 +301,7 @@ test_multi_heap_on_host:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - wl_host_test
+    - host_test
   script:
     - cd components/heap/test_multi_heap_host
     - ./test_all_configs.sh
@@ -310,7 +310,7 @@ test_confserver:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - confserver_test
+    - host_test
   script:
     - cd tools/kconfig_new/test
     - ./test_confserver.py
@@ -319,7 +319,7 @@ test_build_system:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - build_test
+    - host_test
   dependencies: []
   script:
     - ${IDF_PATH}/tools/ci/test_configure_ci_environment.sh
@@ -332,7 +332,7 @@ test_build_system_cmake:
   stage: test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
   tags:
-    - build_test
+    - host_test
   dependencies: []
   script:
     - ${IDF_PATH}/tools/ci/test_configure_ci_environment.sh

From 950dd8e3e5bda7c10287a3a20d85e089fb30a275 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 7 Jun 2018 15:18:48 +1000
Subject: [PATCH 088/112] docs: Standardise CMake vs cmake

---
 docs/en/api-guides/build-system.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index f1055afd9..a5054fe63 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -405,8 +405,8 @@ When creating a project
 Requirements in the build system implementation
 -----------------------------------------------
 
-- Very early in the cmake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
-- The main cmake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
+- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
+- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
 - Configuration is then evaluated for the components included in the build.
 - Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
 
@@ -429,12 +429,12 @@ The custom ``project()`` function performs the following steps:
 
 - Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above<component-requirements-implementation>`).
 - Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
-- Loads the project configuration from the ``sdkconfig`` file and produces a ``cmake`` include file and a C header file, to set config macros. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
+- Loads the project configuration from the ``sdkconfig`` file and produces a ``sdkconfig.cmake`` file and ``sdkconfig.h`` header, to define config values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
 - Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
 - Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
-- Load the git version. This includes some magic which will automatically re-run cmake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
+- Load the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
 - Include ``project_include.cmake`` files from any components which have them.
-- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the cmake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
+- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the CMake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
 - Add the final app executable to the build.
 - Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
 
@@ -783,7 +783,7 @@ The best option will depend on your particular project and its users.
 Build System Metadata
 =====================
 
-For integration into IDEs and other build systems, when cmake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
 
 - ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
 - ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
@@ -882,7 +882,7 @@ No Longer Available in CMake
 Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
 
 - ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
-- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the user. The name of the component library can no longer be overriden by the user.
+- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component.
 - ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
 - ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
 - ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.

From bf10447b82f5c34f9c97bbeb9a879f2a903a7e11 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 15 Jun 2018 14:59:45 +1000
Subject: [PATCH 089/112] cmake: Fix issues when IDF_PATH is not set in
 environment

Support cases where IDF_PATH may be passed in on the cmake command line,
or inferred from a (hardcoded absolute or relative) path to project.cmake
---
 components/bootloader/project_include.cmake   |  2 +-
 .../bootloader/subproject/CMakeLists.txt      |  7 +++-
 tools/ci/test_build_system_cmake.sh           | 36 ++++++++++++++++++-
 tools/cmake/idf_functions.cmake               |  3 +-
 tools/cmake/project.cmake                     |  7 ++--
 tools/idf.py                                  |  3 +-
 6 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/components/bootloader/project_include.cmake b/components/bootloader/project_include.cmake
index 3d583eefb..cdb18a9fa 100644
--- a/components/bootloader/project_include.cmake
+++ b/components/bootloader/project_include.cmake
@@ -17,7 +17,7 @@ externalproject_add(bootloader
     # TODO: support overriding the bootloader in COMPONENT_PATHS
     SOURCE_DIR "${IDF_PATH}/components/bootloader/subproject"
     BINARY_DIR "${bootloader_build_dir}"
-    CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH="${IDF_PATH}"
+    CMAKE_ARGS -DSDKCONFIG=${SDKCONFIG} -DIDF_PATH=${IDF_PATH}
     INSTALL_COMMAND ""
     BUILD_ALWAYS 1  # no easy way around this...
     BUILD_BYPRODUCTS ${bootloader_binary_files}
diff --git a/components/bootloader/subproject/CMakeLists.txt b/components/bootloader/subproject/CMakeLists.txt
index 21a6e84a5..228bd8991 100644
--- a/components/bootloader/subproject/CMakeLists.txt
+++ b/components/bootloader/subproject/CMakeLists.txt
@@ -5,6 +5,11 @@ if(NOT SDKCONFIG)
         "in by the parent build process.")
 endif()
 
+if(NOT IDF_PATH)
+    message(FATAL_ERROR "Bootloader subproject expects the IDF_PATH variable to be passed "
+        "in by the parent build process.")
+endif()
+
 set(COMPONENTS bootloader esptool_py esp32 soc bootloader_support log spi_flash micro-ecc soc)
 set(BOOTLOADER_BUILD 1)
 add_definitions(-DBOOTLOADER_BUILD=1)
@@ -13,7 +18,7 @@ set(COMPONENT_REQUIRES_COMMON log esp32 soc)
 
 set(MAIN_SRCS main/bootloader_start.c)
 
-include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+include("${IDF_PATH}/tools/cmake/project.cmake")
 project(bootloader)
 
 target_linker_script(bootloader.elf
diff --git a/tools/ci/test_build_system_cmake.sh b/tools/ci/test_build_system_cmake.sh
index ed2baf23a..de400fcb7 100755
--- a/tools/ci/test_build_system_cmake.sh
+++ b/tools/ci/test_build_system_cmake.sh
@@ -171,13 +171,47 @@ function run_tests()
     idf.py build
     take_build_snapshot
     # Need to actually change the build config, or CMake won't do anything
+    cp CMakeLists.txt CMakeLists.bak
     sed -i 's/^project(/add_compile_options("-DUSELESS_MACRO_DOES_NOTHING=1")\nproject\(/' CMakeLists.txt
-    idf.py build
+    idf.py build || failure "Build failed"
+    mv CMakeLists.bak CMakeLists.txt
     # similar to previous test
     assert_rebuilt newlib/CMakeFiles/newlib.dir/syscall_table.c.obj
     assert_rebuilt nvs_flash/CMakeFiles/nvs_flash.dir/src/nvs_api.cpp.obj
     assert_rebuilt freertos/CMakeFiles/freertos.dir/xtensa_vectors.S.obj
 
+    print_status "Can build with Ninja (no idf.py)"
+    clean_build_dir
+    (cd build && cmake -G Ninja .. && ninja)  || failure "Ninja build failed"
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Can build with GNU Make (no idf.py)"
+    clean_build_dir
+    mkdir build
+    (cd build && cmake -G "Unix Makefiles" .. && make) || failure "Make build failed"
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Can build with IDF_PATH set via cmake cache not environment"
+    clean_build_dir
+    cp CMakeLists.txt CMakeLists.bak
+    sed -i 's/ENV{IDF_PATH}/{IDF_PATH}/' CMakeLists.txt
+    export IDF_PATH_BACKUP="$IDF_PATH"
+    (unset IDF_PATH &&
+         cd build &&
+         cmake -G Ninja .. -DIDF_PATH=${IDF_PATH_BACKUP} &&
+         ninja) || failure "Ninja build failed"
+    mv CMakeLists.bak CMakeLists.txt
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
+    print_status "Can build with IDF_PATH unset and inferred by build system"
+    clean_build_dir
+    cp CMakeLists.txt CMakeLists.bak
+    sed -i "s%\$ENV{IDF_PATH}%${IDF_PATH}%" CMakeLists.txt  # expand to a hardcoded path
+    (unset IDF_PATH && cd build &&
+         cmake -G Ninja .. && ninja) || failure "Ninja build failed"
+    mv CMakeLists.bak CMakeLists.txt
+    assert_built ${APP_BINS} ${BOOTLOADER_BINS} ${PARTITION_BIN}
+
     print_status "All tests completed"
     if [ -n "${FAILURES}" ]; then
         echo "Some failures were detected:"
diff --git a/tools/cmake/idf_functions.cmake b/tools/cmake/idf_functions.cmake
index bd0aea6e5..b8c0f221d 100644
--- a/tools/cmake/idf_functions.cmake
+++ b/tools/cmake/idf_functions.cmake
@@ -119,7 +119,8 @@ function(idf_verify_environment)
 
     # Check toolchain is configured properly in cmake
     if(NOT ( ${CMAKE_SYSTEM_NAME} STREQUAL "Generic" AND ${CMAKE_C_COMPILER} MATCHES xtensa))
-        message(FATAL_ERROR "Internal error, toolchain has not been set correctly by project")
+        message(FATAL_ERROR "Internal error, toolchain has not been set correctly by project "
+            "(or an invalid CMakeCache.txt file has been generated somehow)")
     endif()
 
     #
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index ff344a967..86174feb8 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -6,11 +6,12 @@ cmake_minimum_required(VERSION 3.5)
 set(IDF_PATH "$ENV{IDF_PATH}")
 if(NOT IDF_PATH)
     # Documentation says you should set IDF_PATH in your environment, but we
-    # can infer it here if it's not set.
-    set(IDF_PATH ${CMAKE_CURRENT_LIST_DIR})
+    # can infer it relative to tools/cmake directory if it's not set.
+    get_filename_component(IDF_PATH "${CMAKE_CURRENT_LIST_DIR}/../.." ABSOLUTE)
 endif()
 file(TO_CMAKE_PATH "${IDF_PATH}" IDF_PATH)
-set($ENV{IDF_PATH} "${IDF_PATH}")
+set(ENV{IDF_PATH} ${IDF_PATH})
+
 
 #
 # Load cmake modules
diff --git a/tools/idf.py b/tools/idf.py
index 402d334bb..5837060fb 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -41,7 +41,7 @@ class FatalError(RuntimeError):
 PYTHON=sys.executable
 
 # note: os.environ changes don't automatically propagate to child processes,
-# you have to pass this in explicitly
+# you have to pass env=os.environ explicitly anywhere that we create a process
 os.environ["PYTHON"]=sys.executable
 
 # Make flavors, across the various kinds of Windows environments & POSIX...
@@ -95,6 +95,7 @@ def check_environment():
             print("WARNING: IDF_PATH environment variable is set to %s but idf.py path indicates IDF directory %s. Using the environment variable directory, but results may be unexpected..."
                   % (set_idf_path, detected_idf_path))
     else:
+        print("Setting IDF_PATH environment variable: %s" % detected_idf_path)
         os.environ["IDF_PATH"] = detected_idf_path
 
 def executable_exists(args):

From fdfe38a779facedcb3d4f69e5169f6f3d93f65e8 Mon Sep 17 00:00:00 2001
From: Mahavir Jain <mahavir@espressif.com>
Date: Tue, 10 Jul 2018 13:31:28 +0530
Subject: [PATCH 090/112] wpa_supplicant: add missing source dirs to CMake
 build

Closes: https://github.com/espressif/esp-idf/issues/2168

Signed-off-by: Mahavir Jain <mahavir@espressif.com>
---
 components/wpa_supplicant/CMakeLists.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/wpa_supplicant/CMakeLists.txt b/components/wpa_supplicant/CMakeLists.txt
index e77e3160b..2f63ff398 100644
--- a/components/wpa_supplicant/CMakeLists.txt
+++ b/components/wpa_supplicant/CMakeLists.txt
@@ -1,4 +1,4 @@
-set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto)
+set(COMPONENT_SRCDIRS src/crypto port src/fast_crypto src/wpa2/eap_peer src/wpa2/tls src/wpa2/utils src/wps)
 set(COMPONENT_ADD_INCLUDEDIRS include port/include)
 
 set(COMPONENT_REQUIRES "")

From 191557db023bb0b2bb340bcd6e9510a06e361915 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 8 Aug 2018 17:58:00 +1000
Subject: [PATCH 091/112] docs: Copy CMake docs to a separate set of
 directories

Required first step before merging back to mainline.
---
 docs/_static/what-you-need-cmake.png          | Bin 0 -> 113695 bytes
 docs/en/api-guides/build-system-cmake.rst     | 942 +++++++++++++++++
 docs/en/api-guides/build-system.rst           | 992 ++++++------------
 docs/en/api-guides/gnu-make-build-system.rst  |  55 -
 docs/en/api-guides/index.rst                  |   1 +
 docs/en/cmake-pending-features.rst            |  10 +
 docs/en/cmake-warning.rst                     |   4 +
 .../add-idf_path-to-profile.rst               |  73 ++
 docs/en/get-started-cmake/eclipse-setup.rst   |  10 +
 .../establish-serial-connection.rst           | 131 +++
 .../get-started-devkitc-v2.rst                |  80 ++
 .../get-started-cmake/get-started-devkitc.rst | 114 ++
 .../get-started-pico-kit-v3.rst               |  67 ++
 .../get-started-pico-kit.rst                  | 213 ++++
 .../get-started-wrover-kit-v2.rst             | 192 ++++
 .../get-started-wrover-kit.rst                | 413 ++++++++
 docs/en/get-started-cmake/idf-monitor.rst     | 135 +++
 docs/en/get-started-cmake/index.rst           | 464 ++++++++
 .../get-started-cmake/linux-setup-scratch.rst |  73 ++
 docs/en/get-started-cmake/linux-setup.rst     | 112 ++
 .../get-started-cmake/macos-setup-scratch.rst |  83 ++
 docs/en/get-started-cmake/macos-setup.rst     |  90 ++
 .../toolchain-setup-scratch.rst               |  25 +
 .../windows-setup-scratch.rst                 |  89 ++
 docs/en/get-started-cmake/windows-setup.rst   |  71 ++
 .../get-started/add-idf_path-to-profile.rst   |  72 +-
 docs/en/get-started/eclipse-setup-windows.rst |  79 ++
 docs/en/get-started/eclipse-setup.rst         | 104 +-
 .../establish-serial-connection.rst           |   3 +-
 docs/en/get-started/idf-monitor.rst           |   9 +-
 docs/en/get-started/index.rst                 | 259 ++---
 docs/en/get-started/linux-setup-scratch.rst   |  21 +-
 docs/en/get-started/linux-setup.rst           |  13 +-
 docs/en/get-started/macos-setup-scratch.rst   |  28 +-
 docs/en/get-started/macos-setup.rst           |  32 +-
 docs/en/get-started/windows-setup-scratch.rst | 143 ++-
 docs/en/get-started/windows-setup.rst         |  67 +-
 docs/en/index.rst                             |   4 +-
 docs/zh_CN/api-guides/build-system-cmake.rst  |   1 +
 .../api-guides/gnu-make-build-system.rst      |   1 -
 docs/zh_CN/cmake-pending-features.rst         |   1 +
 docs/zh_CN/cmake-warning.rst                  |   1 +
 .../add-idf_path-to-profile.rst               |   1 +
 .../zh_CN/get-started-cmake/eclipse-setup.rst |   1 +
 .../establish-serial-connection.rst           |   1 +
 .../get-started-devkitc-v2.rst                |   1 +
 .../get-started-cmake/get-started-devkitc.rst |   1 +
 .../get-started-pico-kit-v3.rst               |   1 +
 .../get-started-pico-kit.rst                  |   1 +
 .../get-started-wrover-kit-v2.rst             |   1 +
 .../get-started-wrover-kit.rst                |   1 +
 docs/zh_CN/get-started-cmake/idf-monitor.rst  |   1 +
 docs/zh_CN/get-started-cmake/index.rst        |   1 +
 .../get-started-cmake/linux-setup-scratch.rst |   1 +
 docs/zh_CN/get-started-cmake/linux-setup.rst  |   1 +
 .../get-started-cmake/macos-setup-scratch.rst |   1 +
 docs/zh_CN/get-started-cmake/macos-setup.rst  |   1 +
 .../toolchain-setup-scratch.rst               |   1 +
 .../windows-setup-scratch.rst                 |   1 +
 .../zh_CN/get-started-cmake/windows-setup.rst |   1 +
 .../get-started/eclipse-setup-windows.rst     |  82 ++
 docs/zh_CN/get-started/eclipse-setup.rst      | 103 +-
 docs/zh_CN/index.rst                          |   1 +
 tools/idf.py                                  |   2 +-
 tools/kconfig_new/confgen.py                  |   3 +
 65 files changed, 4364 insertions(+), 1122 deletions(-)
 create mode 100644 docs/_static/what-you-need-cmake.png
 create mode 100644 docs/en/api-guides/build-system-cmake.rst
 delete mode 100644 docs/en/api-guides/gnu-make-build-system.rst
 create mode 100644 docs/en/cmake-pending-features.rst
 create mode 100644 docs/en/cmake-warning.rst
 create mode 100644 docs/en/get-started-cmake/add-idf_path-to-profile.rst
 create mode 100644 docs/en/get-started-cmake/eclipse-setup.rst
 create mode 100644 docs/en/get-started-cmake/establish-serial-connection.rst
 create mode 100644 docs/en/get-started-cmake/get-started-devkitc-v2.rst
 create mode 100644 docs/en/get-started-cmake/get-started-devkitc.rst
 create mode 100644 docs/en/get-started-cmake/get-started-pico-kit-v3.rst
 create mode 100644 docs/en/get-started-cmake/get-started-pico-kit.rst
 create mode 100644 docs/en/get-started-cmake/get-started-wrover-kit-v2.rst
 create mode 100644 docs/en/get-started-cmake/get-started-wrover-kit.rst
 create mode 100644 docs/en/get-started-cmake/idf-monitor.rst
 create mode 100644 docs/en/get-started-cmake/index.rst
 create mode 100644 docs/en/get-started-cmake/linux-setup-scratch.rst
 create mode 100644 docs/en/get-started-cmake/linux-setup.rst
 create mode 100644 docs/en/get-started-cmake/macos-setup-scratch.rst
 create mode 100644 docs/en/get-started-cmake/macos-setup.rst
 create mode 100644 docs/en/get-started-cmake/toolchain-setup-scratch.rst
 create mode 100644 docs/en/get-started-cmake/windows-setup-scratch.rst
 create mode 100644 docs/en/get-started-cmake/windows-setup.rst
 create mode 100644 docs/en/get-started/eclipse-setup-windows.rst
 create mode 100644 docs/zh_CN/api-guides/build-system-cmake.rst
 delete mode 100644 docs/zh_CN/api-guides/gnu-make-build-system.rst
 create mode 100644 docs/zh_CN/cmake-pending-features.rst
 create mode 100644 docs/zh_CN/cmake-warning.rst
 create mode 100644 docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst
 create mode 100644 docs/zh_CN/get-started-cmake/eclipse-setup.rst
 create mode 100644 docs/zh_CN/get-started-cmake/establish-serial-connection.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-devkitc.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-pico-kit-v3.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-pico-kit.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-wrover-kit-v2.rst
 create mode 100644 docs/zh_CN/get-started-cmake/get-started-wrover-kit.rst
 create mode 100644 docs/zh_CN/get-started-cmake/idf-monitor.rst
 create mode 100644 docs/zh_CN/get-started-cmake/index.rst
 create mode 100644 docs/zh_CN/get-started-cmake/linux-setup-scratch.rst
 create mode 100644 docs/zh_CN/get-started-cmake/linux-setup.rst
 create mode 100644 docs/zh_CN/get-started-cmake/macos-setup-scratch.rst
 create mode 100644 docs/zh_CN/get-started-cmake/macos-setup.rst
 create mode 100644 docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst
 create mode 100644 docs/zh_CN/get-started-cmake/windows-setup-scratch.rst
 create mode 100644 docs/zh_CN/get-started-cmake/windows-setup.rst
 create mode 100644 docs/zh_CN/get-started/eclipse-setup-windows.rst

diff --git a/docs/_static/what-you-need-cmake.png b/docs/_static/what-you-need-cmake.png
new file mode 100644
index 0000000000000000000000000000000000000000..b98d2bbfd2004829a5ff60b156fddefa98b22877
GIT binary patch
literal 113695
zcmb5W1yq%7w>2!?B`F992q+EG9ReaP-7VcnhjfETN{5tmZ@RmsbCa9y?*9gT-t(L@
z&i{Sm8v_S}?H+ervDRF3&UFRL$%vyN6Cyu*_6$wp!~0Lqo<W12J%j2(ga<xJdv*x}
z{6ez%pl1K<8MW@?Kd4d%N`_}p^`jE+g%q7<cT*5_ag?S4z?NH$)URI)ZZ<k?HHIK=
zcL$=$!$!$s!IhB(`P`E$W8&gs$qTw3G+vAd3xEB#*iSWc4z_pVcukf;DTuf+YQ$b|
z|JitdVBTe8pmrlqnhKjBK=1J<Co>&FrTga()g>0xcBaQ46wN>X8=&Xi|MWpSlM%Je
z*w|QZ&d;Bqk(;kyzdDDDWsU8e{o33#5x5?hm|$xk9HdWK?C$8eTw7l^9XG4W_>}#z
z4A0HDpfN2?$ET>sQd{EO*4B2Bi;IihN&jGXH+g+|IZAy*J6|!;$H%95)cD1V7ZJU^
zy;g90z{QXIVrlP1_f}U|`Kr{5v?R{?`S~Tz&(FD>^wVNv*S{qsY-*3BE{cnaDrM$p
zWo1qF_tVy<^EG0iqen29F+wD<PK@IX86hW_Cv)Inz9Nhw6^Zjo{z`4pz0PxlAV)cz
z%3R0H^UMqV8-w>e1Sqo#Jo0V}!5&st#nKiQg-#OZj*gBlO-)TmqI+AH8LN4(-MBqB
zIcZGN5)-$-$HhT3N3?UtOpCSZAtGtD_4T>+Adn$WWldSx=+(_lH-1%3DlO%V#&E39
zIb7t~%I?9MX8lC1`h2bOeC?;yp(-9O6{|1Be4F;!=^ie;Ds<i3%tz;>P48Jy6_#O(
zH*u8aYOKASCVnX$A6$UF(zr$HzO6*d@<*ke?ap9F3fzO-A66p;e*33!t4O8sYk5{1
z50lVoR7*8^?G)8u5)!Is-dQ)_1son8@{}KpWWc1lKz<0HuLyrttN7eI9PyIN#~%eB
zuN<G)rR+QupRubqnp(1w^xbFF?Wqzk@$+2Sv@ThJJH?*V(%Bl5QE0}dOMNmo{h?$o
zj_EOXRxgS3{&>c2Zy1FAp47>}$%5BzX2aG^R}lCc;F~@SoBq2~MH&dU4Lui?cjM@A
zd-*AOjr$$in#s)ekb&oWre422>CI%jF^I(}XU4dLL*2=4iZp8ajBqOPeJGlXHaW9b
ztJ3*WFdVdT{@+K^3=f3buK2;52pd}=uwyR>i=u~uT*nVo(fv~*TK5QfefZ(GBqJFk
zBZk@8nP|1?7<`raR6u8ey~53Mdmsfh^+v>QN=k}#sR~W(RT`V=Z&)%iGXGsmOUuwI
zQWitR>$4q|%*HP_2OUjT3w2i~>U&5##t{(_9Mkwe(;MUCr=<4~Pzk;QYhy8rPm93%
zvn+n+$}ZUbM7j=&#!wdem*rgbm8If%Dnq7|87U5qgMu3mPrd%$7D4R~J|wtCZJnMb
zg<KgsFZ{|}kIz+3PEO6Oi(Oqgs%|??484o4#W<CW&V~5KUep`2MMD!SLsct7vBwU@
z3%#{=1@?PFX|!;A{j0UY-M>KIcBw2zArkX+Y?vI9)K{N+nWX%&K+4e2&_6lefCV*i
ze0_bb6NbUyhk)U{lS;?*n(~XYGkSZsx;(sw(&rBH^g~TcqGg4<Tbb&IZD#A*(_^Al
zOa4`Kj~~o8I55*8Ybl~=tM<30GAv%SH7y-kbPf(mHz8+^n(PPP?WNLYS26C@ev%)q
zLhvY_54A5U9F7eOLv7*)7CJLr@utmKBD<w}k9`XeXcXQ3me|INwcMf;KHHfyp(<p+
z7K7TGdF|FdSdj(jC5WRkGM4Pxu6CWR$LSK}v?2Wyr}E{XIr#V%tjBVs?U>$=PV+y8
zww3QuQF;}|!>KiMm8K^Z6&3c-HHhs@xME8o=tFLI*Jma(<&=-1E<rr#^weQ4TQc5L
zy+pf_jn3vp0C2_lrwAFKM-$U>c6=Q2lEZ2qZOa0Pl?fr?fq{XJYdujSCZ)_Z@W3@c
zE`4$(Fkf*7?h6@hU0l=#SDKDB*HRJ$<lFrFLg5h+#R5isF}HQ+K%gDS64KO6UfrFk
zV2mK<sjew0IpDIw0`3^rVg%fWMEcaVk%gJL>{r69&EMe=%NqS;X~(>-tWOZ&62pLM
zRy7I)K4Ga75F2nWIq0eGZff`6KP9s7p;BZ5&8LccFZTEMueiP#=<9!rk4GRPBD%b}
z=^y^2pb!-oM+HWJh5cZwHL^G{foo-DMLC<Bn@d4SxgN1AijYd`BcI%;U6N}PPPDta
zvhpoDS|Jk%=A>xjw1z<Zmdc8jtQ_v?5wx?jBXi3d4Wd;kjxi}wq`?AKv~T0I7pvUQ
z_cxc9&L&l}!slvgY9FMe=tdVuN0|i*0wz+^i88+L2IuAF5$&4tCpN!!ON@jtn#lHN
zt;ZS4?uhItji*kgRcF0+oAopc^f@1w8P}$qQQ%Q<!>=4392B*%*hM?9eAwbFt*Gz?
z2JX)vZ%lL!HQxeDwpPE2aZ9se7TjCwSYUr9GZd?lV&0iTTf;pS!t)q;7q&I^iYX#0
z3Qfmylve*Nr}=Up*mmkPcXF`6{pITBOhxWfknIb_(kgv36hB?}g?6$?gBq-1;Ds_9
zO;4Zo`i9T#Tz972$jML^zjbRYH{L`Re`RIY>t>I`FEB9P<Y7|7nv9jT@|#B>I`QGa
zyWtoUueBa5I!#dNH@@K1q?s{)m&rmkj_Jr3@8HjNrWi*(k5)Q4U5*XOZpLzDS98-m
zX-1nwL-CxCI`L6vuz}$Db~N?PkmuF$I;YK&VDLFB>7dR?YMgjKeQ)aQYLazRZR>p~
zW7D^ls{cN6W43i3H|N6Vul<aNl3jfH=%YJu_GD*EME6V|#%$$AfFb*o?9po9X{PhL
z_H$KpwEdp)#&$~be~lQfQ}O)vV-jlvwkj_)GzTqhzb^x{bRui-h2H|&8gZGcPcN<E
zdUm{a-vzST)_8vOEnk6_yxZ~i{6Ld*5_@S5d%c$1G4jGdYJ+O$3<fDbFStN4na?FQ
zWLAUE6-Wftfqs5C<<!IDgS)-7O3961?j+0q3AjCfVlAGr&LL;%EdEbUw@l6(C>Z!2
zmJ!Ms{DEeRyTbJNB2KsGT%9w`SCFJDlIfLQQ=-sWjYcoZndoQcbJdn)ZpY|&#<I|T
z+urm;i`#GM{~wo&)#kXKo}TPvzJjqY=l&Q-6xef2&>U=RRlj}UP~@u2ChGA(YiG|>
zUcaYyX{Qj}$r|z*p^(@ykf1%?9J@xmRz7#|rd3x4Rh~aa*2U{Q5Z&HZrsiRr)QISn
z_B6heeD0m5gHHS;FvqE|CZpu!*;Tm)g&>!r$n5^#sjwD8SmwBOoiq6H{y!_vo$QKZ
zCYvfZ`WiWbRXr(bKCDU2#Wmx(KVKUP_IkL3U%BM!rEhx*`9|Xs!Vce)&BF8&?2tMU
zh7*`!u&JcpC<na*0uip%QeADWC<YPxE<7VfJCl^Cx3Fw^Ma6ndZA56O<bJx4?;_Ti
zsukK(H2mV=AY}z^@-XF*2$DGt5RU?`unuLe3ZE-N7Y2k`?MM<n{(rU<%l2zBZV4-+
z0KGm+ID|=N;JcAuTf##_3%K0QEy94XH!VbndLkEPi%#pA9M0us)iR2r67|#mz3ze|
z0h1j$RrB<7l8~K>`;!<#*?XgBiVKGdx9|;1^7GJ)ORE8FhxbS=M>DZK$>0lgWyo`W
zOJz9hiFdX}U}xCH_CcBCF*N>niA#r_!y}-CgPQOokzDIltEO)ZU<#u#TATVJ9bW(5
zs%-=H^a;qlC9Q&EM|U^RP!h+%2ml*WGm|&x$$`W~;4Mi>`1S>VHa?9gHPYzQP=*A$
z=&q$az%ZVZdc$o<<;~Y|xT5Z0aA=`MSgA)a>Ztp#*FUtT>cFoA%yG7})9IuH;NS1K
zt_oAc>CFTmH?7xBH<)tp*2@THB@JzaD-WXzw}1bRJYI}4SFeqLo7~{OTwsTD&_}Ac
zn??7VOqtbzJB5XY=2w1#9ULk!5pgX_G_mjq2!X=26bG5nF-mzReM}f)tHd2^-D#aZ
zd9wudcJ!am(cXKqt1RH&URm(m8sCpO*IlVuxKs&-yj8+g%*P21@1G*SX_jrx=+S4S
z*9ys6Ts)NdAn53_;JC_QF>CgI<6ut6cI*Z1YOtw*u6s|TYVfNtHT+QK^~&J9Obyd9
zvd5wUBdX=>;sWF5xSz4sKOr!&U!cL8u?@%M#;gBG2~3XB!zSc>-Ca^<xA*M!YW;$f
zeOrOGPsL}DIo*rl^Po;dc&)6SAQ?V{jZVYy8ULM*V1JrtTikKokvNB*f}Muc_J9m0
zWGGKD|5H~omp#t>b6`q1y*0#A3_V{c1=K!hc7j74+fBwu4aAh`J@LAmE-m^Q8c4@c
ztB|#Za7{Q$1@PQYsFf{7^#n_xvvv(0I?Fw*2o9~pJ2XC`=upEUY)E%f3lz8Pm-c@c
zooRUoVs>pfB>OD2i3<MyTI80nVcPMTr_4^+L3K$>-t1@56wm`t!^NVLY7@sx2`Uc1
zYLc%i0;vI`MGaQ9XUjw!E1y=WM<y!h=EnUliFFK)yY0)iTSR}(U1ofq%SgD~x*^c)
z&q%lm?OF;jFw5G$tXz(~<Z$3yOspU={?2x2Jx$Cg{Ug|^4lZ-#T^6V);T|HcT6)Jx
z{@lR^$;z*ISgM2i;9SVYdvV8VF8KE=JMQ<7DCWZw1Onj}egD2k+-dUDPt+3|TiC$J
zgs)<jqtzX`!yjSUtTc8xexbvRPTe6CYBmvfX=|PMtK2qAmd$08QaOIgI^0XbqRzc&
zF^HDQIQ}Y6AkYAxTq!?&){Sv_m(uj%ygn>;7>@$<+i7(#)%VE$lZJcQ8Q9%6sp-ti
zWXc||SouYeiU2`4O;B5$PIG4hIuB;q{j;V`=ZcS-z0;LjZ+<!6X-~%zZ|#U@8G#S5
zh<@W|Q8$LjO>oiOAKUZJ9P#22tA%7h)zrM)TbW{Nslm^=Zy>sZjxMvk{t&h^fv%!V
z+I_)C$2^?F<UU!#xEOBcr_v?U{@@-CYWTwN*<+eCu-tL=G)%c1hE|$KUR4-apUUrn
zeX~7VWiAZ^4c*2{7#^qLr<Z_CVS|m0T`-WyR-mZV^X6RH;X7u^>y00V`vSdXL4()|
zwzmsP;WS^2QFm8Eu4v;74lcAtm0fidO5JB1InVA8v^u^te`{g0YM;`1=~uSOF@1et
zqFS|BP{Jx!4929>D2L}7Mi0~yN=lBtZ155oK(r2u<S1$*LZe@X&B4C37^l-jBnjOM
zY!>DT6(nVI#auL-Mb>FJ_j2A^L&#J5UAJM;nzK;6dF?nhH$BpSdEv_pQY=Jw5DuIY
z=!~A&@*rq(UPaJEc1KFW7!)-QMfWHxct^;d8en?T#&mi&XRdA_gV{xYL-b&7LE?&c
zJ;%~PQWO~3J=``;LYmI*;k>MKYs*9w>Cp%a4nKNF6yf|l)_!(%CukMqr;JE%$-~_F
zoRsw7u$MaR<;thVe>U7>V(TV%dAPq*ZFFTrg@-xFK=%8XEu6;hF;Z^Sf8*d#Fo*!s
z#%R|f-X(M(okl@NQP#a`Eg7x$zkFj!8E07~nkKrS=ezE2tm4>J6E$_{S&UH3!xG*j
zCEq3yB&6^;=jFFJMjN!Kga-$VhUNuaMr-xZUi#!>Mp}y(aj7t7vhK)LmBAkdE;5uv
zADY;Xt_GA;i7EXwY>=SsHpDELzqBPg*1Y?`3RUlQgI6DVH-t@Kfdz_JHc(1H`XWG(
z#Aszi%SIT98yFz0#in@s<^DXe`pDk7%+|XBIfUC8vK5fP;sU2EitH_EWt=7mJNrzd
z$&)w@LAu4Oj>EsXkx`6}D-z3STqb$TA3*z9*dWEsBOxU+3R@z4{BE~gXyKdlCL~RK
zughq0Ms_?!Yt~B!JUy`ev$`4jwh-KIrYup4pCy_hgNdn^S;j{&HLOF$Jqst;R16Ej
z*v3OE^H(S!oOnt&_FqKud9QXe4h|QwC^wt$>N9mWR~-3bCp$wyZ>Z|FESLBiK|05+
z>;070<IB=X-)0?ot*qVE6b8b09d_uD<1;ZSsrCv~7?1slgp=wP<m+h)6ouBw)8OFX
zg1wwpe^WA(dGDOFejd8V_t4e}tAS_ef_3v^-5*DQNp(l3xF5rVO8i}eZS4A%#GLXS
zv-Hv=P;&_*X>Lz{)bJl51Uu$#IU#FXG&D3gGb%lMlWRBX;dWr^?`WxXX}LqP+xwg_
zce;HfsK}bNb$WI0u=UoOi8F6gXr2hBetPL@z2DZ#4DF>_HB=wT$w+9I!ooLlZY*<c
zt57I=iY4U>W(Ttc++mCtk&r#UGRTqk<#s?t31O;E!!zlot&pjl<}fwcgVrQAIuaFM
zp^#<vgTgLxEsGE}Ya-YQTKQo8u^dEJl6hPs?k1^{_@qL`xYi}tEUX;;W;vnQl4G{K
zo8wQK&bOSC^co>b=97ARacM`bi7uBb-9M)54S2U>ex(?4zmH)j))(#Q?4)!WNf$b>
zkpxQ8WmqdUUE&P)8fRx`-PuahhIpE1*wixb?d*;{?v<QQJu=@}uoret*)yzcar|1~
zl$@ox1ub#P{77t@D4CYzyGGlEosgt0B`<_RFXBkQx$uxHROaWz&Vr-{f)8;y@683)
z@CDylwvf-BW-|2Wl<4-Y7GcWm@C{gBqVqeiyYbc<Rk~Dv!`yNR<G4yUpZe@S@IA7q
z>)cs|b2_$kMuMnpOV!BXF2i+(-B=Fu!$V+T^l+u4H)H0}#*VeFLhRJx8E4JhSk3Zs
z5aw7S96yf-x74i$@q`Hd$xofGBLjIGlW~$eZL2rhq)=S(Wv3HE&MWah5-N;&n`oqY
zgmOe+b43h+;?ob70gWXKcJsB|OlTi(;iZ58T8YQvbDahb#1a)9|KS@rGB1$9ERy@#
z0OIWr-O#vqVBwnQT|%zsq(P31k!|H1kR=Cg<AMDR_1iEcq*nr8P9THwrFGWxU;#ZN
z!ehR4QTa(v7;xhet-2RGQkEC7U+nNT4BB;;*CBNRn-dLQghqhzEuHq*?p?yQgMj;w
zTXJ?S(};BaxZH&Xta`2bm6RN#`2@D>bf-<jfy+CDU5^vm%4$QncYcH21J?K=JhsnY
zS~;oZdbaJ-uO3+%pA`ALwdHEMy(1ql(h>ENd{(iw<lt~{jlJ!K?M<IW&lR>ulVv25
zNH)K_MK8+3Oi5uSw)b$gk=E&pfI)Jwylng9Z)$lfJ^kaIv59)3%=64>zs=X#9C3R4
zJc*D?=dBvV9d^Qs8<p<wag8I5YDUvJ+8vAGJ2t!|h^{Ntw^z+cVHFoIzIqEg-&x<e
z=G6}h3Di7?n9pGI&3m<$=Zi3tl%!W#Gmtycx9lD`QA9Tcy?D`s8BIjoNm%K8pb@4z
z{ldOGvh#bB*DBI*ob$yFe(CN}8gqjw^{(p|Cc;`uy^G<Bqd7HF)LTmyZv2b)BviZe
zmAIR%M0-{@`8P&%E*H3d@d?re45@e9Y?alPen=JC9hp!SqeY!;VICPMKBu{5mj$FY
zbh@0%;pQLu&dxo5vqK4Bn1shXGzL{OsFXo&W>lkRpB)SnrjRleY;(d}S6`xGgSUe`
z@pZ(~>WW9S=fg;w7m;p0r|G_@t>XdBIrbfFv}|F9)=K;~n+U`p^(>c7<0rNM!+BV}
z_yXkSpD($FnJ|!VT(e4VO$=`DC*m(%)`bf1Ezv%m4k7*mlUjQoqf<4GK$CEw(Vlg;
zc+(#?FCdKSjXaBSE`V^s+N*T88MSe!G9AIWTd(@36Am5?lmw2PsCqeE>!Vb6GzM-r
zbxw0Tww<cU8f;;E>F-`nY@SP!I-lKOxp7Q&-;fTsm&<mq8vFD3?0jh#?-%IuyKkk8
z0rQ1OCw(6|FJb`QT^k`y*Vv$+$6k71R9+{;7EgEZ+m|_sNK4%wir;d&z*P>#$~T`N
zsNT%Lo`Rykf<GS^tlKXqoQ@jON!q@jU}x0d*GXH-{tWj%=NH4Gb`{bPse2HYq_O^O
z&6b?ol;DnWb9;$`SVn|s3s{TiN5=Hw@0`cYs7FHXZB9R7Zfx9L)WLgda;v`VzvUG?
zRkT6e@WHG7S>Cs!8(l)3(_I(jhs0Ex(<qglvV>;)-Eb6-YjUZybw;#<mn<2Zh$N9h
zC{eoVs!Q0Ew>)9(kt<(rSX;voS1pGZj*?Upnrfrt6v@+1G%l4ILUKuRQrYxqteT2e
zs$tH=Zv9{=JnObf-Zp3$oI33=U*qjKZ0vQ+qw45@pEwqKd;9vnqE?_7eGdAV{aY|A
zRB}e5Pe@-AK3Xr~IH;oH-5U*5=^xPe@Kv*$>+86!^pD@g2DvsaQn9fqg(!^9ELc*z
z$Rgxf60HWxfEUSitl|%%%C~UWBzMD@=n}bz?c*$3%X;3gO@k=%WHe6i4v3tM4K*%t
zdia{H{D@rdVwB%snd=^`gwvqS8jNgWFx!48(!eOZ+IagW^%jNCQ!1*T&T|Gi&ti9Z
zg*fawk}pDqs>wHZ2ft~PBuNt`JU6Aj7h|FWfqHnQ-PK+9-N2rpOVe90hXO&?XkJfm
zuWe05g(S5x!e5%PtFv<=nZ@X1zW&(z$D*;1DbOw6_%~5e>I=UBN-kZqDN#>Foi3|}
ziE0#n0VGAM37EzQ>}TSZFWb%w+v7_Z+B3sX%B*{B6d7<THv%2o5z>p<(no&=vY)Y_
z7wUxNi*PJ`n3ON{<iBK?YFsK0A2G_M;9tRXygfroRjWh2QQ7M%EZ!Go>@{JzG-bV@
z^K=<>rXy`<%6?5n)g^KI(5v|?9)QBsHvM_g?@dLIi}J&$bM9<*Xrz34YFCfEsEJ3d
z7lr6t%C^rO<m(D9PnzkE26Rdcejf{|GL;JUDk`>*412aDkc)uP;vt#FzVT&{g&)&r
zyBtnT`ouM=)mXN3V3CK#w50+v#?`W(PJ%Uc)sYL=3j`_44g|&%rspBO-BJmfGLr%D
zKWzUgVz{}vsld{><;S5&f#@%N<oOVX1#|@GpC=0P-fcY`cIsH`wFkhov<%f~Ceo~l
zhP^nXVyB<>CSDe-Cp4-`{dnn^5YqYXJQI@Ob-0ymgPMrhCr;Bo5A#M^^{E`#-P=0@
z*r+=Vsj+`ZQ$V|_V^!**d*p52=3<b*H8k)(yMwZrPYmd;$B~#MWkEL2yoafZAGTzW
zg;P;^{-D;=M|1N9%~KEOIt(0QWIjoz*GAxcQr5>b;L+CJF2ZBC)<gDRbt-UOH7oY&
zcG?G#=rrn;8*Mh*%_BW$S3y~at#SCXJ7T||4t}!hJV(mn`Ug#%f-^7^1&hA1Rn|UK
zRbR8aBbGsz6||%Us0t8O$+N%Z-utDToE&BKDl^>c^F58BF?X%5X40_MY<+|uTp8^<
zX)C?kkmi^(a914~as#hE;l0)^9C`@8Qq=LU1(L>8XS@fu)n=1j&#|xvrY#ms{4dbv
z&CbMQ7%;`Myn)`u7y9+Q%MviX5tL*SIySPDx_gx>-<;cDy;E^;*?GsS7LH*SP^)Ef
zX#O;)zsJTbIV@*SO{a>rjB7!l4!ckQEa|~oDJ#cy52f&o<}2g^+}Kk#1o)sI5gUu&
zzAiL-gf379y+>_gu-O`IcDku4JKZ%0+3CV47cG31)?hc-S){-8*v6wvt|0(h>jcD`
z;e?GWgiqb#Iu|8m^NhP7dAZ-=?1$e@3FY?d?D-UhP&^E@MiD_S{1=!25y+l;^UU=L
z#J#4VX#Wgw{?;`XGshTD`p}z40s)v9U}r9hc+cUyqrg~D#`AZ_K}R&>!pzz{%K-Ic
zC$}}f({9g`RWTT#703j~so3(B2`#hgA;;1u&%?+yx^STGj=}QB;Yn#-K#2|TXl)vs
z2?*emUewMtXdMMb;$u5mI~O2(YNH*Hpl#40qbk4ycyb|7iV>hqq-wE1fULP3O(mUa
z+ByCElFiv^SM%rT9Woe=Hn~Q5PaDHGmr>-}mb3w+hvK-U)2Vy*MMzCEu{3kd&$|0N
z<s6E~Wc32w(Sa87d?gI0jW!?+6J|n@=AyRGivz&Ca<wabhbkv(o)D<t-gp;`npC#7
zwq~nyuE*k}7+&=-ZhiMI&F(MbE+$$eVkf-k7+6BY#~*!3gU0F<H8yEIz@E?*v#_mw
zZ^>UxfNSzDos^S@x_zGL4Vr%E$3Ru~>Dk$BKx1eO*6?|XBY<xEt5T`wX-wlH>8o}E
zH`0#Vnwy(LGosCPM-dh<zmb}m3(m($Bvfmn<Su%Q%3r-w84vo|IChxU%aeZbA|RMi
z5t0?7w~vM6rZMXf1dP&v$ZH!wz1Ze`S!Nnvwzi;xsr@Nmd%Uwkr!io%8h!I&os{59
zsX$ZOB(V}?Ql#Dy4RiCScw4Q<wCxg0r6&xN*W{Q@qxFs_mRI8)vP|!#HumYPVn;GK
zlK3X;o2d$hHA7N3KZE->7F2t$;D`uEyu0RL$+IUR)=Et<+tqj=!5ayis>eP0A^>(*
zgA?KA<82dyx`zz3O2gT1!~r_7_{Kw0aN7MsNR~#tUam6SMN8c#vlaPbBJ1;_hJ)N2
zcD#DeBwww#<{0(}n+pulo#kPJwK;2D8%tw;;TI4R;TJe05l=5G^#f5;Lt{<~nK7No
zx4zSam7Ir1L*@XExH;H=D~X5It}wXuU=X`RV|dnHn?~xSPgfLy(WkdEZ@k}%^^8tR
z;VRuIp`4tS7A0FcP!(&`gtcpFX{ntR&sW12m?BCW(^EP$Oj;vqB*Hu~g-5w+xdo7n
z%mK+L1@uR*stMzkko(09FiLhbYjPRCpBO$4d=MbdFS?!Y3MH{yF6|DKr2|Wfw@~&+
zLYtwHktrZ3vy@9jQ$273(cAv--gkAa1OLvJlm|pLVDICAski~c`1^?zKpFDB{+W|A
zORrk0D+6fU7v+H91=N=Ff7oK+OK=PTryK#e3m7K)nNUyOAZhNrs<4yy4+BKGT5C{k
z?K&zzRvR&gL;hB!=82`B9KV-;#LNW)+8?ieQMGEKLl7>OxVX61&H3Jjo#db54FHqn
zLp;FVbMZ@+i)AM!2mB5vm`Iv56K)3u-yZ4d^>7e~vwNn(Smz~=qlGnqU+n*Kz~-!k
zO4&uiPp|O@*w<FQ2zaYvXlVF#jBGJTyF`VGib@$*f#@$&u2eALa(XEvB{}xU7~Ay$
zkFfYbR#yBeWX62V?rm))6O}^yyFDc%vvZ`AlxH7{hM2!|0|pD6^fNY}F8x)g{-M)b
z@9%EPT+hr1P$P3h{Orgzau1qrto&yfVn6!xdt9d*^~bq?6YzU1QURUv@y?HujY`2p
zU4XxThD-`~X-&;W91Z1btG85F@`3twZ!NMj_cZW87}Vo6Y?iYzM45=SwYA$pK|#ez
z1<DKJZz*d3svTThwa4?d_L54=;*X@+&qBlVyp12@TMkzTwa#LlEi~gO`x*iHuez)6
z3e_suL++csHy>pG$p>mk&qgKeUJO8wWR3jpVt=>p8;ni;JNy+#hlrGv6e{QAgbYx;
zw#k1_p+aUrkV7s)_U>sZ1KyEdVpfw89(}_8zc3Pz+<TwqLp(_4lgtZ1V$ed!Q_iZ~
z!lWf18X9upb3MHb`x}}7hyxU2wXwi_#mhkvqQ7_)Q2k)7+}+(b8(dD9^g9qQFE4E*
zffc|@4&WnhI$&+Cmg=>Oxw^QB{(bslncRxVkPw;)L|Z~bU>V5KF&d)-tVlz~gjwqr
zruAzM4wWyEfgdvZ+Z}(O@sI9e*EgSNX>dETHK(!BS9LecvPMUsD%R|Z9Bn?)UD@&k
zV?hgX(wsT$zalP@o8Au;+aA)Macj2a4*t^3bfqfZC5jZ}$4R(>HEMlh`3RK=AY{)$
zF*i1VC1YOrBI@h;@QRVg>=_0*yWUV&Xx{vh=;<#P4;52&<$PU@VxQ=EMt7x%6=Hy_
zCp6F32K)vNe-|lzmdvNPZQPXCHK&$x2Ajs0dM4f&_bwli=dXu{+AxNd)~Nl32r3xx
z3@$Ns_unONWjp^}y8eI1_U-w9qP`vNJ5&XRWhutatf`&Y{QP{Sh57m7UlZHBe}!#n
zDXGFwvowZJNWiEJap;{|9068^CEj8R3x2_cIJxwe_sHbkQD2|}b6q$GjuWqryi^eQ
zh>gmN7ry{q^L<@7saZ8~NN`$HWNQ`jV(BJk*{xQ??LFhPI|FXDw=~nz+3=B9Nfixd
zf0B>yNzO_%sfw=Cw9(H^i=`Ly1bo_;nD3|@0!lQ4GnqjU0`PDWeOu0F4d&$nqiND8
z^!oJA1c$Sz?)R?d&WA!ROc!B~(crB@j^^5bV?ldiIQtS3DBDN%dq_VZ?*+<7>xdfN
zxfCXI;Fo-v4=cq*IMkAj<Vh@f^M7Nz<6g*m`tY~&j()!U&~Wpf`}~0mzd39#*x?}b
za^tP++frGX1MhCC6ybHKEGAE9G)~j3(w#`s!y6uts9mQQv}yEQ^<wAcDx>C-L=D&X
z!wD}F{5`-8;TPR!?`1}m=w7Z3AV4dat*ovBOBC27BmnIPxUU2w_cyUf6e4;S!Y;aR
zy$i^)O7}*bHg#wC48*^5jeSXLxhRoow_nyt_upsVP{6zMW^zC3!T{l1K4&LQ3>_+l
z$m;BFhXsV^>diJVp?ZM3GX1oUP9YSR#TAsEwuZzGXf8;!4>Lgxxv4(kwnR<$E3d+c
zn_DNn#M^&`>Ud-`+ua4|&U|O<adG7Q7&0=Mt=u_>psef8R#8%G&x01>hSv7ozaWa^
z16^7qd`^rUVFys`76t(cW_z~AS|FZA{jW!aVd7P8D}MIwYoT>d)4mw2n|K2kx)H0%
z`m4-XImBfS7e%exv(aW%Pff(Bu({+C+o*LN^>8IUs_{ErizW~yYj~GIXGVsc3L37L
z7P}V#F9D+i0~2R=3EHe89D8@iD~a2!lHD+Cijw6!%}94!N$rIJ9LnU5a_JvGdhpU>
zIAP1gWKVx7zxvizjAsT1<AQ{gu8F<q&dM~v*9w#t#?z&GjQ0P^KRqxCj)tOQ<WMpM
zaywn$A``33MS_ijLY|*wFD$x)gqFm-`K@#sT}K;(M{=zE1&%KQy)rOfzUsz-K-v<o
zR9AOH=J^ElR(_{&+Cu1tQkuU?+Nv>)#7~3^?=Qk)M3R?P6PmE<>oX<ny#NMo6Xzes
z&I+(<tb5&GApnFG9=C7cX$-y;RrF=e<+2`C78ccXOBdvPqaLb}#8nO+wX;Y?EW1v0
zarS+oOD#S8K=@aUh3=93FDkqOhP;V27afV+Zp#H4^g0<|eVn-3=bZpg$)0kNI$N$a
zxJhAtem?VW#(2y+B>e6K9@nRDrT?m@zmxi7NOHenI_t9yrPRZpBEC6YxU%2yvq2M<
z`<5`gd=9CHIwJFUN#ZGgt5M&AKYDp`#!;HzXMX8AZ#l`p^KZhmd1p~|44y8tr>U<&
z;0FRq=b|<M0->OwMtZtoP@`gFvuA4UH+q1i=g|(BaUN07pKJgWB6uJp(H+mtjWc@4
z@I7q3_AUHg;qu_y0-$mn6Fel^)R4VRaY{PD%@!j)MNbKP(fshW(c060GOkcJp!6!?
zYER#UTBgm?m>m#JGZR>?7aQdAgdQ18O1M$=hECLz^mIDpH1}g9V^;vVxG2IFH#d6`
zsF2YHPM^1Q>+pG3wKs`ILZ+A?{>6EP&0m!SJOjT3lM&S3YO$)!x4MhUv$pxEG3t+g
zo!OjRA?#`zffKqOQ@x$Q;KXBkS<uCX^Ufc<SXaFpOtRmsJ2Rd^5UDaU%Yh$NkEeTn
zQ6D7{s3Zo@($NulLDL>X3naU8YU#vrDXI3_KYk&Vd__Wl&JR2O7y=+O$v9^3VY)WY
z$QKE`mi(Ugx@;_Li+Q7;VVg7#v9wM1Y`afzJ1d4YcNgTau?23i1Z1?KitLTX4{o6*
zJ=vl7cn@?%`2uzKw^cz>m+&Z5O<xZz8!#2KxKgjqFkMM@B4u<eTH`<$atrYnZ%=ef
zm04CDg8TuH8t@2G|CY-IQ#+QAkEB2Qp1QZly#`eqHriCatezgU@%olQyJohrCbi^=
zd@@^}BZ77CL}?CDIr7s#X2zxhAG#neav8Sq!0{iM@!_2~MKs!C$?EuRReaz5sO~9|
z_HJNdd1b}tDUuL`i;2p}MAWCGXmNA#{A1=|U?~1<TJSCS35DsQXGX70eg<X^F(^3L
z_W7L`OZ+wfRokARYONw802kxd)(ma_Aund<=5in5Q_lQH03Uy-RHy%#gkDCjZ*Fd$
zr&WJW#XPw77qDVrMD|mNN6=Y5QA2MZVW`d0`g$y%)jX)_zcB~BMFT*o*fBMQ5BS?w
zc^3eT8X3|eEh~Eg7~8Px9QSC%2>};}A_!fsD2`)AN{@ww#o~N-=EM<z>Yjj&Rb~kf
zz{G8cnxm~QB|6O{^cvL-=H9e%P=AaJ#@_*`AE;gO2bMlo^6?B>*QSlGXOpG>J1z%O
z;?OBz1A4^eG^0IAJ&zP5-~V240su|Sh4L*n%tpK+0L+C=F}a9W!XGQgx6%YPuz>kQ
zW+`sH)AtFrHzFB7UJA>bh?rO_&0y^5x_OERVK3f&r<O_>83OQd*k6+UKYJJ`7c`Pw
z(s#klqy;J^0j;`kqSr?^-F8kFoWSewo`QLbG-|<NEKT!oSux`tar&r<qM@;IeQ18j
z-=e698KnP*tOszn%g8rSw*1M3AnGe-<|v{|sDrtBEKp2e=_9UO^A{>&e?){qrX+uz
zf9e%)V#=dqB*wX#Un`J|JmO%kTCdI)S3pVuvt)NqO>vk5Lea#($}2U1^X$WBEe(q7
z4{7ZP#*Ru(cAq+*v|Dj+e_RJah?>6)yB<e1zXuqoOvk<1c}&p}v#RaV(o*W3@%#$F
zV#pu<cN_p;_8qWaq@EOPV9U5rJtq0*-=m}VHh|cAd3OP}mdpQ?9sRe8`NMkj=64YQ
zQ24#LxP89%qkBMN$<^6e6GCJ7xV%UJGay%c0GgYcRMy`}5x-LWbe9MK@+SioTnq=m
z0z4HmFNul2?9J7r_5WpT|3KdPz5$WWIxMTrGleKywvTALS`G5qLT;#pcVtxP`EY?O
zS5+04rP`M6Yv+{uj^VywzG;$$i4Pq&N<x%FlTI)IG4d~<3!r~Cz{(k3X3*W|po4m1
zviye+{bKP`0>g6K=%s2ifkL2FOH^T&>YcmIk7OV8{nSH;s=#9s3(@&L=FQsy(FWWK
zykV{*Z6m8lz?InTasnYHWY+Ich`~<zJCtXxjcAne_+!8Sj^$fEO4O4>IW!T08z_Si
zkmCPfIZaf|ln6tRc(9q5Ni0PN?xhj?QI{9gpaHKVr`;N2BC9ER8YlDT|MKlz6aCA#
zgOC`P^Hh`cVJhg!`8NbH!z^~>!10t)yfjhqom<lbXm4B;JUT(3KvsM7=JO&$PXX(H
z7pMo<@bnYfp5qr6zxFHt7AxwNWMI;4dO_s*+dVYuB!Xhf_*s(x2vPRt|AeeTRywTk
z9JUWm&IgSLrS8_8-=(bDte$D#ITMQ2(5Tw>|Nnbe;8Ebs4#DfJU@qQ+!WP;GwSZ&*
z_TaPB`~*z@F94IG{6AXhlXmmEhDE_UsAJK?_G>x9FO|l7)5-4~hdu@(yj&2YpPhl3
zWf+(hhMelCS1=M8cT8r-1$l)6k+CO`m8ys&tm>6#O*?At$W5n34<hxc6*g6Uf(_TL
zCW=Bh)wkF5T@KUUL1zeuqT=?;v8QKQqvZz|L1<f{qtV);dD}1Xyso%Xcb!Q>Bj|*3
zduf^HtZ=&S*L`ihy!`ev1_80l`(OSUvnq9!V&N{P&r)@$9ik~Mvy9r^r|n;Nu!r^1
zcg_y%pVKZkY7sHz=TQEnc6z5xc!E$I5Y|>L0?zQwCRm!5PdRc}pgz1S7(3Lw#5a*=
zh3;{HP76=;M`<-EyE{}dF?KQIH#>dRFj0xy<h=KA_`4TF4n^;BC7jge?IEQFKP!F;
z{m!wziZQDNFWML+r8W5CCevfn`6!=*@O(E^o402dKF^xglDi}11JJ0zO-`O^{z#w9
z%+7xPr@(%Mc)yj&u%Ec>)ww(fPdhK~ZkPEza)a^!2l^N7Hc}k{xEdc)<vnk0Hk7=H
zyZ$m>JQI$c1pwK;X@J)|&a1oJ$?__@1!021L+N<`o9$v8^6>2Xq9}OSxVUZm4VjH}
zK^e_}Uma=KAbyQs&Zu)CCo9hOuZ#wiAN5qs%%h%wxs~WCO+H3>`Nvde_d*In_R}Vj
z$-fUzW*;hVv4IHw+!Q)3(>S78;1=cf2kwhtSWZ2`BBIEf{{Ukz99$4S<4R`2W=@Uw
z#p%jqKSDfXXfPSF;bN2P89BI~tTLbIplR+k0|R<8deoyY<2i_dfuYP79xd~2&GQq)
zPwt7O--lm+$%yVXWQn3<a8!;SMZ~tyHBcCchldH%{|!l*xXhEZeK-9oFE!!ir0?^~
zx3RqFd944bJ9v0D&NfF^|C<xyJ%S2A*Hoe=vJ7PTDSSZWEhF3*(t>e?#kt<Ut+f|k
zf+u^EM<AjnzD}_s&A&NYrIu0hAGJPMz>oO{AkR0~IC|IqOP&WgHc(hWWed?g&U4T|
z{>$b6Vt|CSbpu@1OcpTi8k#z9XVP@1Lcwbocp`l??%W%!n78oPleAsMLSCmB_plWZ
zna(!b{==}ePLZTWQiZhrK*ngDjvU%SEX6Dg*Fc%BFtAt4B1f~Zx#WVb$h7;wts`?K
zHg)f(Hk#Ovw*@e{nG7UeUS9t}IFAfh2J9w~9DL*B@oR9}=aH)U4v$o1b@xiGN3*Wj
z!dx<FX?7TOCnCXmTKb4$3|{zyp`i?NRUP#@&0mcoAHtTUdGw|Vd`Elek?Ort!@)z>
zx=Ys4qiSLd{}-?u6MAxf4v&^_<33Hx$-D$NKsW<Uv&b_*|3OBk`e7r@3lD>Y*SR4u
zu-oV_-7q*f_=VdZ5;ou`7xGt(=Nf)}(t~w5K)!pC;N3e0S>3=;rchW7C$tn>s)r+8
zj-8}T!_dC->{uK;JG$>aDcv1Ax>Q?^SaMxB96gR?&hWDFG%PVrtDUaTprZ1;r0`5`
zfL7n=%L8A*6y8}tyE-Rs9J#r&P~GxDgRK)I!FD_PKA0e(2J_=lv#K}NTbLII;K+#r
zm3Cbw-qJ6a%?nhNl${K~UatC>-M31SeH!FAezrBXu^LCOao-B?NEmWUaTA@Zhs*7l
z)ND1ZCnF<I+^?0>zWU{13=(OajVs(mvLCp!z)<Sj>S)YI%}8jaw&r%u+c(-A;=x~s
ztd~`eXt0KhFD-5;-Mi|mI+7lRV><H>^Pe085l}^4MS|u9`9JnKfSbC33W=n&C3`+l
z6Chjn*|t8&;z#RJ+YrMCjNl?BKn_bopp3RlcQuL=JD4!km*U`JRO|qFV`Fc>8uvMY
zJXwdG*vks+C#vE-qKCHJB5emQL-(VP+`@cY7<w%WSvFqj2tGE20)VsN((e=q(0PN2
ziTNyC%-#t_rC<i8m8tW408HpT#=EIE^0fyz18zzEo&1P}`KSP@Nf3X()YaV`=y}{r
zogE^bwYCK?Ouv04^?_au+G2up73ct4k;jg;fjexF5foZX0*evy6JXaAE{pn4V0h#W
z0l<<A1O@<pKL6;e`d>-|Kv!k<7RVF6DKP}lcE7Zz1VFVtvTayEsR$JgO~Pddq%+{@
zpZ{Ue0$q7fHMB(q;}5V7u3k=R-N5l#?4L2Fwymk3G1DKq{j_j}vjX|aCMmVPKa<j&
z;UKvncPZXCd%be^EB$+e*}@GNU^#t|=hxQO`W}ZoAtdZmzMpS<duqCLWH`!$SVI=Y
z%jo+qM%pH^$kq#<f^uXT?WRK|uEpq2Bet~N=_l{-kCX@0c{dymydr_>md*xfm@@}T
znC#qK1K=HisAFC`@U9nVH$lTy0x(qvg3P|_ZP{zA`*!Ngo3^b>^Lv30#J4Z!_jf+R
z>J8MXhSiEoM$R-N>HQ$P*t-BwXbW@=T~AL>3()v9T5cryD4)gf0ECh}Fm4!xdx`#+
z924-3JdOVR5*0@~->+10ZeD61t=<9DJ<2@M;n^8q_fw6~_fAdqzT3`_Mm=NIV1LtS
z6REya@~Hm+%Xz)%7aRnodt7Yd$h4jG$a>SYfz6n2=(YJ0xRggbkp=s}0mbh)0z&)I
zmbr|o<KU7oS|Bx434wupp$mg;4!yHO7Tmq0K3Vz==VdYnZrUvfy1t!(Lev;$c&Tgi
zs4XyoIpdu>t}7iuUaMF9Si{C)Lj`ont?>&xJXRXWMOe@bJIaB~kI;!5im04ZL6e<(
z=k@k{f`u-k5a_uJmkQD8aSK{1_bSvIir;$p<ESv&N#4Uc)@bNG1_{UvHWOxFv`tTh
zuP-lk0VU-R(Vxy5gz<&D<8)mW#ElX%3B%liZ?k>ESvSkj`s=EBWk7>8!!c^6DpUvi
z<g9Hx%_&PqmxW!1G}yLrcDZkR^|C2&hj`d&Oi4q4kp9Lqa{5~n0pFIA->)IPqxiJd
z-iVE|&7M!FXiO_>rzFl6zuzj7Fd?r7PJNALN3OrWglcXc!|(NsFFRI~bx3S@Ua=>p
zx2wZXaB(5NNiv%}c^Ci=RbzQcA8_mabHtN??Mg{;GOfGM#r{aWdk|5>_8IuBfkCSx
zzA;2wV|Hoc!mDeog>Lr-V%Z>2Ol{{=tiSxqn4cNo=TS5P^Fv>6Z&X&O>8q{<L1s%p
zVw~>-R*2*#k`hoL@PGIof9w5)OR!(a7gLaw^P(MF%d*t$%o@<=McgMf<v}{bNNpe^
zuT`(`L6Hh!FO7idtg}NP<`T@U`nn6b*Pp~n{SUV*mFK_Qt`2r|{~{NYrgRRsX~Uy-
zIAHtZ3WbI$+U4`rbSg238Jmv8+EYD7CDB>x6)!jJI9BhNy_U>+-dOOQ5_7AvZvRjG
zrdJ!Y^{HTG4~CYhDY4dryJl<&H1&#34MgbTo9cs>Mu@6l3ugtW7Q~O35miB3qGLsX
zT`-V}fVF4)gN@LGkXE{OBVO|`I6yYhi6+@7{g2O77U#?1z!(~{(J^vi2u@p7AMudN
z^M4yuv&XXjgQUKeqc?>&1YFqj9e2|Ezc9>sv;5jZ>WO%qSB9?n7kHyp(FmIC&Dvfm
ziM;PTUKL(quXdNuqIOlHeRaQQmJw&t*5C*GQ{wF)V5`9e83{Q!us(&x`R|E|A%Mn{
z0nm0BU}xWiPF0XJV~4sMtGs4gwq)EeQMIT-r~2;034Y;2v&^QY+roRbY-AdIH7Pl{
zZ<kIrGfjOdgDT}M;leQqm4MdQgKvds>DrjW_P-fh;b1(}7T&Dw??wFw=asx;1KKa2
z_hX9E8sdUTNJRB5*}h4zqQak817d<LTrto*{MmApIp|Nk{$5x}w>w{pox=UabrW`f
zUDQh#KfmlmC&N6p#44H02noXYfY%s^V`EAf&V*afimM2x)mX!$Be8il5-q1pW5uFC
zKG`sj2LlmnDcU#K9IvBIC1oKQoO9D3Tx~p@Ag=W9eQ&ODYyD%bdb%Y?civkV3Xb$1
zs5y}}f&RlDp#Lz|Y<ZGkK9Ifn^`nTt_WWKGgij^v5qA9rxeosYz7h95On?`NgckA;
zzDCBl=0+R-*KG;m`^RmGvN;D((eHhH1n(CQ4?|bLK3MhtMRL~deGE%<Bk^okS-LE_
zD|S<qCMtcSCPfSOH0Sj9Yr!tC-JfSm7Z=Pp7)s-zhPA@{36rQt0Awg{wovFtar2Qa
zx}YUq0eX1-Hd5WtX_Q`!FV>Y}dc9;3TG+yMKLmRp(qDU!s_>q)yACWIqTDx}LyKv!
zf%DUt-1?o}=Vp@G+G0R2b?!Z}wkJz6y@a%!fqnQsoPU#;`^7uY2Pil2EpidPS}UsF
z3G>NZ=ZH))Y@i?P>yY6@4r}c<ny>Z`(n`NW>(OiLw#|R$-gKb6)&8GEs|52W<>fK1
zT<;~0ks1=x1JrhC{Bq<Uq))=1u+vvFHh?@ka(uz84@*u?{xh9{KKEWVD7v)01wXA;
z9&iN75S$5158N5zLs0a%uPysGs*x^T1kHcm9*9<csSRNR4|gSw!#jITn&9*~*#pn-
zmx)C+;EELrKOk0vH^p@B&w%(lt!t&kv!(3ovMO6~MnXQdE9k+;NFh+4S6j#&toeRl
z{p$?)K#VG!uD?exAVIDX+1i@$yox9d!wrrazTvAHMd;7e%02JMW>;wQK#x$8!4kaz
z6fJo*FQ@{~TlAghB20Ey^(I5iNKdb4-FwJjiOcfK@UdYVXcC1V8cNpq1~}jV8uUF7
zEf<lR@6MA3>gRyY)lYQmocF5Egf<@VjHq_Bw#8x;Izs)j4}o_l8>^>t!-)bG=lsh2
z_z@DM(p}{^;)<3h<dFL_ByBTg!@|zJAt!9!n}N<nG&bfVAg8Xb;f`>th}{j5>h2k1
zkF-Za2z+V_43=4ziRcn8p_^)sgyq5^&X6gQO_xFeZjUlJjg>`_FBwaBsi|Q|UXd*q
zNs!f=`MLzAaxhvm{{IO;Yc_f7sV>ElZEbC-);YZ0o+x;Pl?is@Qc?pRgQv#;QeOcY
z3p#-QaXK}m{eXZ3&qcqjnnZf%m*+3K)b0_xS-7gi8?gkIzdA1@YYeJjC=4euu{|7M
zHrV(0IUx^by%*f5IV^CF_4~)ksKe`ll{1X|YyAo2;@oa_ffXno8RNy1&w92Q3GM@a
zy)}1SPjsU?!jFZLZYKaI;-&!H+HyF@V#`Q|NSWmv`}DMp1QY-?Z)j|aOxr&C1_mOC
zMZA0q7;2c-(LVY*H;<7;kP490JMOgsydBV#sdFd;oS#se1|TFrQWppCR&DGL1oTez
z-=TWQ!m@dfD_BPU4Nii9SJN)hTN0<G7Vid%gqvU*e*UI1<$_pSUm#z0n<N5<8l)y9
z5Lj?AW&(to!ls9!q9R5A8SesscgwrIAz4=_v!Uy?LF>x&W?t)kvDcXgO1PD>GBW4`
zJw4wd1ATpbWPplIM92+bmJ0y+I~X`AAt`BxfQU$=@%3YaxfEb!ILthcrBOmw0E`K6
zdkYH-C68XMv761!O>V$wnUn5eX7<ZVT|Mz2Wg4aO{{DXBWBJsUgCpSTDo`5dr=rUF
ztgW5uA#o0<E5>Yu(lSDBDk@W)92_+X-**8b(&N*oPteG-W8A;%9=muy?5K|~4i6tZ
z9{-^Hbo@gGaQuS|a2&v%DJf3r@Xx_IYv}loXG4Fw5x<(?>_1NkgdZJU0+!5pS?|_*
ze>|Ct`{u_1<_@L{d|Rk?9j`k|+B`OkX-uVGinZO%&h^YWFGJNwu~sT?+zuLRx~?yP
z4zab<)2%U<SmL9VP{vH4d-nM5v8y*1Xt3>0U^ZC00WRCmdF*q(yu5q~NwT&o&CSIT
zZon(osj(uiwgxkRhZET(x!aLv1x^OuZH{EL6VE7k2|S%#AR;1i1T^(7=n8mTJ6y%o
zrr!a_Fr*4##!N~Cl?k6~)L6y#gRtE~j&fBWzVG^jhOKve&VhE~tU_ds?~Pw>1%=$o
zvyEa5Wqlvw={1ylQoE#pe%Q&V$*MfQDx@lDiF4M{xN}RP8$cV-U2gNgItNm-G&VUX
z1Qh%sH!0Q)u*yYH1GA~9&6qLI{HKRf8Ioj};06`$Bj9z<3%Kp5bzYkd#)cC>AiO<N
zj4=;ij@NqaMrQUG>TAtj+c&>_cFyW?K4Xl6R#*r;u;=2nkAZbzT2xRai*C!aAHtO*
zMNyc4+h{+D<5W^ZjaOT0TrIlJ<5w~gOgh(}vznZIK96~u&FN+ym*;ct0AuF=zDm1<
z(NH!PBZ<}2PW&8hbuYAnQI#V-{Z5jx(GSoDp6~S*=QS1->`3qBH&+CttM8feS$&p$
ziyK;TadJ|he+SgJ>uh!Dd_`^_K745Mkdg{B>x+5YD{R4m*}c{ayf_<Scr{=zGsz99
z7v%zMPJX=Q4*1U7<8NL49LI>5x1Yhlz^oIqr{tj;tP2^ty6ja=8S?Hw++PT|Uo1E^
zh$Og0V6w(b1i`|>;?y<qaC7&m$bUe<@rSh-h1z^A7@AZAvLFL~M-09#;yXJ5jxzx5
z(kK$-nAj%#p4Fgj#>)m#Z)R6fGpn=S(ISnw>FFffM_<q0jDmkz+dcP-uSR~c9_wIZ
z17f_Q{1JkIr1-o_Jdz}KD<#Bt|5Lt5fp%kE^6$`nxwrdK@Mj}g<N<GGM<@i3Aq?u3
zh_ZZVI2?%fvRJ}zYB<T-0IR#Lz3#6^$w-oJzY!m(J>NbsHs5}~AhDkU3|GCXjIMr?
z&^4SN1^|i;8|Xa#UKR#N>d!PVSc=Z#_H7HZ7hCuU1UO&>0S}-{F4F}L0Mi@NI;9C9
z?ALl(n}PMQXLb`DSa>9B^jWIGD<m3B1C48K{wQ{s&s@wy13)8L1R?lY2GQ^&BMQ&~
zwUWb7k4hGu$#@=Cj!a4jnMgo7uyz^@65PZ92wZieHt(lLf<uWsKR!PG5umNpM=hP`
zZA{nnRaFVL$MY552qx==_?EwX$?J@%QEgG%sv(&Q&mFNT&)`z)EQl^Lf+q9%GgWeO
zGRd`NM(azQ$a>Q;DmC&HJrdS5kMkdNQlApbI8p6s0euQL6MRz%_zo*HH8u4QYFp@0
z-Yf!usMbBVXFjH~lJ&>AA)tJGD#Ym+8&gpB%9KwM_1*pvNE8yvAbEe1_P~2;c?_r`
zlA|(eLV$m^69Gv90_ZHC!B)1>PKz!GNJvPRw<p83%fP#di3Qj_`bI;EZUpv2TX6Ns
zT>&|tjwZnk-o><6;|mZSg!K?#yPGKTWDAp(SgN6r<=nPx%_EB}vll2AeP5{t?lAvK
z>c=YJY4@P+l#ZhVUJ6z7o1e?{8~LS2v$H~M%5OnmYIrn42N7;0$S58wwQOokTb$h_
zo*z7)oK+ieI0R$^Vvrz?c3dofe^>+dtZ(zvVZvaX^m&a&$oh>e6xANXs&4JoJLd2P
zMj#WV^BS|VB<SVU5m1ijUaJ2BeZoW*d1Xz%AcrfJGsqN46XTaQgd5U-cQX9{@pVq&
zbv0bLZIZ^ev18k6)Y#6BZ5vG*+je8yZfqM(W7}!c=B)2O&$&Gp`*L5dwI;?p=9do9
z40Z~Dj{U0`m96}>@p;>qrH>5$d0t+}Q~^_SWs*r{2LT;}-*H<o29GVM$9hU%92%dN
zaA3Q~w`7b7&Ks(n00o&~-;E1N4UaxhmONz7MJkqH7<nKC9{Btlc!IZvzzHE@g#ItP
zunrPO1wSMLs}@f$D#Wm2?fP`fqwvj5erRvQW?D81ib7rg`}gLUc@%Zmra3fUL1{);
zo5nu`FldCmjvLJtz`Vab+E_MB&>S$<q!|mOX!L`#l8s3|t0#nXcdXd*52j$Vv9V3y
zb68L+Wv~|H0=xD#A>9As2Fd_(MCk^wQm(<rS1KW@H9A#RD(`eX<!3mNdIZv6Jr`H9
zW>6{A>C;sQR8(Ll^mUslnTe%1QIWw!z{Dqi9?6w3BrI%i)3Gl#KAeulyPx11$(2VN
zs3a;DBS#kIka78F#$;4T?xZ-dp$d?(*4NjsOe*Oo57TI!WWKs$H#P=ed97CK1Os*5
z5u!gvAYj-@W4Sx)?CP3S45oLPZ|+8&DSD()@!cDO&+Kb0FQ=0J>3K2-@gN=ZSvZ`W
zwZsxTZ2fVN^!0g~eyszx&_6!?cK9OF>e~LVAMVIY%V@<o+ZuQ2&2*9fypdH{MT2}F
z98|$*P#{6~UMoiC{o4`C7uP(T4-^LGZ6`v5+p`cpnY1t1^lQ96WW_3;-8cP6G1mm&
z8!t+LFcYKNiO|RUy^Dl^CAP6_FqgvGFA=C|3jl<r$@3C>de!?JMTZDvY3X=*U+Ob#
zuA~2Z2A`RR6WK(hrQr;|J!)j4FbE3jMS<`B16jDfXsF7{MiE7PW$BE729zTWa^#7E
zd~Jj*?ktg!k%@(A1}V@5?Pxf6NOKe#KCgfNOw3B}u*>TJQ+ckJ@@UDef5)J|8!C($
ze<1$!qJ6(fogH`+e)r#BO*fJ>bjGw<5YKjje*4G?MD=kOn+glgSgx>hR0K>Hk)tHO
z@@c|lLvH|z;dRw<e1N<P?9UhnvGGcq0pJhsKOCaEI$gK$=YON(!WWsS<bz5T^R*qD
z7Oa{Fa^P*_418edJjT1^0x&6k0Mpc=Ef7?@<G_dpDv(4LjBd*B*CkRZVhGaT)z<ZV
z5?KKy3ay6$#&1sT7zw7sYcm#1*Sg!<O?dq-uuyf+{Nxp_Uj8ehEl2+F&0B)bWYLQ0
z-gDiTqf4G*)XK+-Xmm%v*m<enUmw}unGh@s-4s$t+uYAr?uJ=CPm9YX4b}h@c`kXQ
z3p}!F7{C-S>SB~QXP)6w(I)$c9B{=<0L-PVMrcg8FK1L<2wwUh1`-7EABhVOjZt8X
zPD(Esb(|POK<bcO2k1b?`>fFrTA1KvH>4g4`(z}3(*di?#v8~>7BDPED?kBsRwx)5
z{iyC-sy7xtEwE6T6qL3b>M*Ms3%m;?4ug2PCR8#OTQ%4AKh=*xrQ0llg@v6A6b713
zP83pM#>I2CDSck%6yRA{2y||ndm%!oDuP5)7tVzhVJ{IqK^;z{kdlnrKOwE`cbbI;
zVCz@KFRurf%*(#n2_ls9(kuuEWlmvZW74O5C3N0Ph(5}$E-nX_&>YwaQt5&{OWVyv
zRX0>11sx_@6mB{?8O77D`H4SD%zq&u2$9V?#}aTA!)CG6PX!MpWQR`43mLJK30&d%
zXZB#Ai2IA=!{XtT<M8;pvymEeqVN`9q$|NcpWfaCe7qS}8}wv3(q{^MkzBSRemwNt
zhoghjhpmPpI}MAj%47GG1L|a#{vc@AO3j+i=UzBHOUvWW^b5))d%~o<and8d7bX$B
zon$V+p)B5dh})5izEQ~~xFu(uy0na;-TkQyT4{x8D}gZmZ1Ud5%Wy2b@w98!LSgs<
zzI%ZrC41!8VMNXpHlHTk%GcciC^!r#>P-JUoMv!ZW01n3LZlc(=Osl(^FYrE&T+B>
zma^0nJbFawEikOe0xx3kuE|7d82u?CE^fLueUmPMRS1<v*<NCr`3B!OprS%wVMVj;
zW)8)fYcAGaFH}B(^EQ#00{8SByp{;~T~%k?$-g~w?<ZezyXl5+EitTdT?=);X*=?g
zY=>!ypRO%`Coe*R8ANWq<A@cS5OktvLbi4i(ZF36+H~l=EvaV2dK-g${-+A_tuWk6
zqdajnKj2>nl7`n?F3;@{<~L{R3rcp51tazoqof&Jiia>kHnyL%20r@CE{#pYT=cN(
z8-gbaHeP>V#L9SnE>5Dhwm$K?9uc{?+@q=1(2LnF{RA4vM5bD6W)InR-}ax|+vstM
z4lYJd!x3<6YXSudZzy|hvt-<V2;`}S=rvG8fAPCFn4aTUwSXJ$r-D1IQ5WX030n}n
zy?x4uuiY<~5pN?Sd410~AH2O;BhD*D9aGM2F<{K-rm<mO!&M7Hz$Iws1(MRKXiL><
zgv*u736t?%IPpWaD!k4nJQ&H1)4^ldHnc>)(DeA=S}LK9pRb6OE9`fQ*&=5BhF4qb
zaeuGYuByuuCnTkiZOE~#EPoDFg)SPu7*efJcj>V*FSnl_EfN#%(1?0u!#i=k$0JF$
z@+=XXg33}_!yj%O@>z^-RVh*#A4%Axu~Xl>&)FiHBe&-?`F40iayBaOB9yX+h<PcV
z^_w!SXeq*+;E;cQ(E^NFH2#Tdx~ljYfi0dOjqSl=h!kehXYr1RSYNryg5&NV;n)19
z#tg~dxPiLdGe|s&aNpuVfwB$W5A<-zniK`Lu~k&p5b!!a-d<h@N|V0y>|t~&bW2tg
z%+;%lUhb!A#MT;Mlc)E6FLxV?v%s+edX^xOT{Jp`#X#L38AW#Uq{1=#<>CJxuYP%`
z*$IYzQ)$IM`e#b-Hf&+_iE?;fmC->OJAhYUb8l*0jrG*kcx(|NF$1bdkzvRz4y|`x
zT2WR!53NqNglU1Jd5(_r<`Fe8x+)vZ`gp$Fn#0V(d}nSKbIsN0OWx~jKw?&2X!#f|
zFNipna24y=UBm0;r9f5Moru>9Yd3Lp=jb$iv213~ZjCN;eMlxkpGHfo*w)p_=mVla
z;eM#Ia+h=`+~@IZV7?zmx9v*A#Du<Ze{cT!cGP)K9j{hDmi>z_+k7uhp&}ex(b_TP
zmOM2^j}IHy5C0x89{U0OlJy)KeJqpSmf((&WB63FI#FDA#4leI#Dbg%MW*0{O#ArD
zE~UK#9ZyP5dlW4#OGd*E$eB3Ba)Whfp{`bpAi}i(Gl48lhj1d0$l{_&=t(gln9zF)
zA4x2xic2-|?7>@AJBx83U7|wLlmeQWuP24Rq&=Tiq=Zu@Q7&JufKh_EIC6bvMRP47
z0+;mo@Feu-^1#dt40kJmF#`_$=gPp4R;<T_LU47YcA9FGUQ)smK(<quCdENv{G)Ht
zmdX{a6=1~3^w$+t)v4y_vC6g1W}H!0`!74O&4UVLz4z(OP+2JTPKU?aGo_@w4}wO_
z44&6C#e-quGCG~13Wck~&)dF_uhs9OsmJDv|7F(?)CO|8hSH9&BqXSvJlWD6rQt~U
zK>+XXLJeKIC4!RndLPh_$kP4&+CKwAi${r)MlW!iETo28EuxpRxWtl-gG0+l0a*-n
zeRET+07q5TF)4^nF2WF&#`iO{W>CB%*}#l}gpCb53WD=SgB*`u4^gPdhX~TiDq&o$
z{~Ry$o}UCIk)B>j+3MgR@vXD77;iF*N@#D7Z;{P1nwO8y&cS%H*u`3*>v0@l`w}3^
zB^v59`<_$4@Sz_%hPWFM87CQ?Hr;Typ@H|9@=rA}KwKPh*6eA2B3%q_)PgCi$h&Gq
zd1C_+qWbeIGeE2vTiS-Vw`*H9HO;q(tGU^#VM_`a=5#cp$*g<x`jbP(KRZBqN=cd7
z+@obD#7+yK!1rGTR~EFO`#vIc|Mg2uq)V$vUQmvbFFaYK#V9>s;)?!ymyrECc~qlD
zGfU_vSzS&4MIe=9tt?1rj<Zg+BGEWj(pg-ja1Bt-`8bRZRw`%q^s1snd#5xD%55$<
z%COXk()3bXH^}}=k~Qze|K3k|%<&ruA+bg^`|nSmWIM49DV*bbp~F&O*rglF2oOjA
zH7!sSyq|K7Ga4!X4M|q(TB5MC+L$_<?UrTWY7y_l@=RQB`^4kN(qH}-J?_2r+RwDO
zSsC7YsdQwst>H0PXT@S}>+n0j3(9i;sz3SHUv&-VwucYZ!DHd8UH%7O@9(Sl4|`&F
zmXUOsk$BShA3p#tTp$hgQ>os3mnSKH^xHa3)9oIj(yr`*Ofk(U83hy6dZzc-I2TB%
zj_1n}E<L?~5<{7{m>?B(85z&$cWMPf@$90}yl>%&xv3DazOcn*W#l|8QehAhIs6DT
zxL<C0ZWcX%gYNFk)$8;z-OrXsBKM7*9^JkIku9UL#=#CJ5Eyva+X4cX?3Gb16>}w)
z3ApBZ)hs2X3<F&~a5~-2!%i637Igh|7$=v9^?e*<cJw`$7#QQ<uq_%G#BoyAdhNr}
zru26%4dJN^o)#7s6LNDS-RyB@as<K;iq$VR17P^@Gt1Z8`S?Ao0;wiFD7d6T#Yf{1
zH&L|jW-*G*H_52Tk@K8&td`r^YV|ul#r6=)FguLNPbB1NW29kanf?3bDjn2s^q563
zou?fv<F9y+Z_XQG5ar@(7PhWf#I~6UT>;PktyTw(LAp50j5e6-v3#C37^OI>Rg*k*
zK&v1vAX}W}#5`r#0gL)xkP=+drs@0_CQz`&Ov+*BTs#cx&ePnGkhCs`$8oy=okCLZ
zaDN}u|9@3k{4m|89zaO>pBRx&?P=yB-hgA8xMX9SI1stZc&|_G)?xAdwyw3N%=8@0
z)BX3>&+mPLu{cW)O}md{Tjv#@+TFQ(`cT(-DB6~Tt*-2~&eRa~YhB&xF_+UVyo6O#
zU`Ee3b^`}j#}Oi+@BYH>3YmIw_~KP6$nJi|DcEWX`%ka=v-bwWoHa*6dKD(56hyEJ
z6{%&i)I4Q=O7yI}B&ab)8l7A_XPDRbALPJ{6d4DD*2Dy}K7WzwAzAt5#ay9=oWxhj
zz5BWVEE7Il;Z%Cl9n5$NW)Qr9$3<Xx7Yz&&UIgN?(*E4`UukLiu%c*&jb__uW_<yQ
z_bu;>-@c!eQ1KD8XtXGYY4(T4)#@8sf^&m`+5%yyfkNuuRJW#p)*`-~-H<Yibehna
zi=Tjy+inO`JU<DNg_;@0*W+>|Q0NWK`yY8@NWI3!=YeGwENg2Ybz~&bAJ@hblxBPC
zFWyV#3&fyQaVIJeGy$v>?*?9CDnV$(eWa5Is>o$$OJa6KDv6^FYY!4%J)B&F@B*SO
z`{**k{l0Uo#e6xdj8gR$j@-6H)O^dxQIcnBcR6+PGGaB3hvaJyk~5j8ZKf=0!$Uh*
zoE*!=zsahEiqHs+hnYS#w&YvPYoGhCufBh;gFwP7{_^jo<p0x*ZKNOGdQGbKq}Zkc
zaPIpYE~1Nkdk=xEtoj)@I^xi|#jl<E00lgc&B^NsQVfNcU10~d!yytOAI_CpeMBuS
zE#c4qx#mKdbsDkU&z1s<zM<sUjRjk!KxHCPgCb%c@N_9YCrAnp&&*7SdgO`X9gTY}
zx`7ZFv?`)jF3<N*b_Z|n5r6(^A>1+KL;LpUSt`0Ue*EG4awRkc8y9w$$8}&;G%NwP
zRm7x<*3B^~;;@TbxnUi39Fb5U7TfH|<2mcYX#p^>Vneyy3}2p1S36|%`#bF!p%@dK
zA5R)4{K!d^lk0Q|Zho-Kf*sX=7Riz_&158z2eA)(oP@Fh(_lau6^xGW4e$GOC21pz
zfF(A?u-sa%QO67!%ph*OAF`F>c6#9I`Y188Ts5~QVEmDIf3j8qi^Bwl(-mjdBO)I5
zqigp&WhBz0FN(5)RU-8q8Xl5$tXyZX!HHgZ)5U04eE^4=L8vf?R!z956|hPnCp@PO
zh{hb%q+Gju!{E<|bf)_UKY_fza}l(ZAjiDs+0r#?*zldicCQ_IncbtR;)SYKB#}7T
zTF|&khsq!rocoMFmWtYA%@}1W!C5B<2a88#5CD^_64FAmnUX-sH#L5Yr)>Zy-6H0M
z%-M4&lg}K0f6R1=&(F_C>yVo(Q*vDMIx{X(1+$~VIosMw%@>SK&3x62gMdg4Qf8rr
z3r8hRzvr}Bf@?Wn2@OwYK_L+g`Q`fr;^ro?7JK2g-oS!=zDUGJsf9~C+1risc_buL
z@$0+$T_Tn<B0@8R?WyI<>7WkFZNt^-uo<g18einzrFpW|!Z5&+Gn!;BmzbUnRU{Vr
z4+^&b_b935z<`s{Bgo9GSZ0<DA(U47(CUdhtNM>L)xIVsX7cT?)!#t&J9It)Rti=?
zy@DXdf=Rbft!xy{n~f+lQzs%$FqH2LlgL4d9_XjW+`);N^x)x|_ENP9G5YZ=i27?N
zrg1u&_BbqlMLL@MDG~vXBS^v(rjeb4$rwWO*2aJ|HO8JRYu|v$zIqkW*~S#bGU0v^
z2Y%NEXVAu#8U`d;!dtQiZa|vQE>NjF@W_<s2YJavs*b>wU^Oj-b+;WnPS5U$+^Lv%
zpw@fE88=twi}K@6=@3pC=-&V2L3mWwS$X#H{qy!l*!O-X7vCt1BZu{$^CHZ|N+xI9
zUd*a-AHoLMK6%cb*Yz<Ando7(2sR;_zHjU=9pKp!?rXh(JFQqb2bZ)<4MPIg!nC^i
zjTKcPER#kc@(S$Pyr!fwo@{L8NRBn|ELKr7@0(vdwa1lI6l7r8JSU`HjMp7<VtIbn
zxO{W-@gdp{c#~P8ANi7cdyIMGePqa)?G7(s$ik1&IMxXdGTA=~OpyF_I{?eU+H3pM
z-qNGAULp!NU+CQR#RpENsu|r!GV-BX&nmPXsag-({%j>2Y#P2l8V8@Kg$WNY6A=@U
zve)9;mNzyrGok}}-_rYaNbwxA<hF*uR@%@Y6<x~Y#Klcel~(tCAR%~X0wN+h4x`FW
z!o!08>1qoo5FM>Tlqbh#`V)i0=bvwB<_qM2_pxE}DXUOVxAW13x7~I<bR_)k9KO4l
zAN|hB9%EV}baMY*2Ni^t$YmDkDMP4sbD(Hl@?LTyc1Vai4tXaOn9~+c7na~fllaOZ
zkJo*V_vunz+$#i!K!N%U+Lz+ah0)F1MlU8tEL$?x`B4=MLp8=}?qKJ38yO9aD55@M
zQd+(in)LT4y%mF$ZRIB3mJ1Ss6$||8ue%5fx|NM^vZtWsh)0f$+}Q)V7K>0;o$d<O
zS%&b~$jkA`MHyq+y|e*zH}8%C5vtG%aI?U)OvMmZ+OEgJVav#Ml9L84f}aKY{z_{j
zcaEJb^qr~KwYy{zMyf3^_*S^XODRRb@5rwZ!wKa(a0E~UBv)N!YC?ihr<)y7hZqEj
z|2rPLN0TaI#!PSf7AsTaOWx0c5rEpGAf-7#(7p8J{9bVq%=6_P`$KD)M5b(IZ&N8>
zG<tco!Qo9E3k6nbwDHU84^=CTi@Xm)=H7qImA~wM$@^HT)f#=|bKHp5DMqY2p*8XU
z@&}K{3ugrZ3hzC=HI=o^Gh@yQ<KvS!?s%@?*jNh1@Z5Co%}0LXO80VvkMFW;0Xv`c
zwziCDB&uUaU^K)kfBsrjvw(7G_7t&^r3be;#^3MmuC<zTxUj3v*Vq!eT`fS5-!||D
zFcZ<YFclW<qj_+PjhwAGuE9N?^Nj35h1WapQ+q`oW@5FjHCu-h*;#O&go<$XZ!Que
zXLEkd?R=~^p7sgJ=d+w){lOalu7!oiYtE@dl&)HizjLzl{n*e4!aa*Kq^O2zAz5u_
z=LCiaS82$wBP8a)tev0!W^0jnzQ<kMugOYa<yryVWD{qd4`HbiGfF&MiJW5+x}m|@
z>E20v6h+_pVo8V7b_HWb?4Ycaa)PK4rU(qDSVE;6BI;vFr#JB4#@8GKlaq+YeJ)$X
z_oYV6o@B?I9W_IZZV5+;A<{6neO+1gOrK6OmLFsmOJB}O(6J>rAD4nML(p50;s6fz
zp2I77FZ_^4&@SPqu>O;yo<CsayhN{ngKjq!Z`~RecyM$?58x7=KorkCA6UE|0TXa@
z2#rPh8tMOnOjrdI%8uQ)Fs*j$kTf(j4haY$QZ=J<Ew+JW**zO#U9+%`%<G>A=Rj?{
zbkhTUAB1s+%SH9>zZsjG&Sv6%v05p+A~`&e3O*Z?hD_Ui`%9kRh=sW7YdSZ}V)VD(
z@a8<yldYt`X0_&bf^hjt8M9>fEte$eH{4}MS3()2e{a_=OTfa4A7sPte)dVgnJ7Fo
zcX&7&U2N%ONbm?twQM$T@H+&QlMLMUmLRcUceiqrCX)_?Lx0d0Cpz*0BB{z%(3xxq
zS`Bis*6QLYVju*BSTrFT5mC_6lKkt70G%8|@4eJ)>!sO5qmb|OuHBmT!Qla!5FH8n
z@!%ARLMR3^^Nf`uUEh%7FctOQR0pEf^O~uPG69`V=<sAl{@4C)XI4wk)GJxK;?u~s
z+!`Sy>IocU2{984KOw=8Id@4tKcX0K?{+sf7y<iVb49L}7krI))*axSb}s~_r)x@v
zWQ*gB`oCjbcANP@Af-Qp>w}U<jdfUPArH-N9e?RDw$dQ6*l}y;_exrjJ~f50B=9Wf
z{1q{N>IAELWWr|Ya8P9Q)N*qZxC-lrcI-eMu9oc~AEXz*E~~$YI{(r%j)h7S)1un9
zHoje(fI~ec9(nZAE7|*V4IcP1rKse(2@u-!meW}+DptcVVhnlR$B^k~5U$wl|6vWY
z!_m0r(vTXFm0EQqJkp_~Bq%6Rn*j@%y;xuVrA7+(`MK$Dft6tdV>2E9k&0QqM=&kw
z7Ihuc=ikicui0&)n}$DyT1-&Ba|fUb|LNmyON`?D^zm(<PX445X_BQU`WDpIr=hMK
z!5-jtzJh!_z_JUrgJf@N47K9?Vn7opiQU8A*cj3tD>*Ct&H3R(MM6?v(ig-YPx>WJ
z4<!3bPk*l6nIc3TUa}UgY1wu~tc8FpF$aw%-y4WlV(+4-Com1Mc?;-r+cHf~kqY}^
zS<cob6}>B@6v_)%@=UC0w8SDmh*>{gEF*fLphU#VeOD|UQk^V>SFZYjwx<N`>Q~i~
zl(|s7CvU-0D`QRaUb329Z*xe%=`fGsaFyre{ydU8siNKFhtFNB8yvm5x6Ak>?vux1
za_?u9ofq1hTWPd=h8Pj4HCXN@HpyMnU_A(PK$~j}g*=m^7vFlBwSO^A`S}Gps`Wus
z)ubD%?Z{0R=Ki}7pVd?jdyM9+ppzV(;SoQY?EOzxow@$3vq|!hREyavy)Y`belxl?
zk;#UJrk3v2NfQ*#e8`mxSZdc6b~+0M7yqo)92<FactcheIp7mwI=zaRyw@wZ%%ZZR
zI^GNfKAKuuQsZ#|1u#(A5y&ozn=hPJtTxRGPa>;A6v%(d%=A#DJSZ96dB}>tU6=HA
z%iFwq+S7|C9uoaV9OJ0wCmCy_-%0k8i@oMaa$*oJ967odnr*y!uH>e<3Q(n$F9)ly
zYy3sAFK^r-VuNAj(XVibm;oVM>#e|>1mn8zgJk<-2g=IsqWD><NOfR+9p0UgQ=;VO
zgjkLwf(l{iD8ENocp2^roXW+)MNIR9+so@8S#+PL3w)yYH#DMLy`A0NXp3pE@nx0<
zFGI-v>7ucTKd#%w5;ill1F!oZ#;1!lia}HtSC>OmcUdkAb-dyq_jOnyX*HWh!*>A<
z-jkZ`2r64WQl69&hN<gFPglQSaY2=fNy(rpQEjoWu{epA*x{Nitbd99L6C$iwNj(Z
z`p$or@a@1&kj`xL(lQF@eRaXPxtMmug2TSP<=9}PvtM{0wL*c_^10ga(_Y;HQaN8-
zVbV?2jIYf^Vr{OZv7f?GhsbD)qtG5(%oUBqYc(}7)h6s<CGmL}UH2=e$QL^E2wDhy
zf=lLtzRE2iLr*g>#EtuPQ0v$Y8r@!0N-ypExUgi+Ui>VD#xo*mgpq@Rk-l#IdVQQO
z#_gLFo3>_%kjko6_=6R`sUGlCVL@M4=j7(b{wKDOm&XLEdL~4x@9XW(`|UiY0EMJr
z;Cso1pDitOpBXjY>I`yX_Oe#*Ea<=Kcsb(h+td}2MNr*A@qEVU#WifFfR|Z;FkQvj
zpCz_=(4Ir2tjb39Arj>{-d$~Jn(z2+Ukq7-r8Ooh2@^@QOze35a_eaP_Yd+~i!H3*
zH$mkhA8byW1-u!DZC-2-lI`u@lcg3y#T>y%U{D~QUncHi5=8V<orzQ3M+=pdFD&PR
zvDr=oxy$n^q$!%iW~DaNR;zHX>4U5tG0|u51>SC}9y$|0^ELiV=0qhBp1|pAp<;e^
zaPa{pF9HOyUJC-VL3;!WF~5xCZU0~20@cd78Y$F=i*@8|ZigXs`g?{&yG$s@do?>9
zm>+azos9F${7@ctzXG9rQ4t#ap%K2}<Ph1L<9#iAs!{3k(EuTY&f%D7rCSb>M)QzM
zMK}hN<7%-;?MY~xBN4q5^=1kowi0l~<-~~B=YMf&8RzwIV}XQ(+Pyjre6iIsTh~JX
z{pdHA4DDznh?EJPAXid23PL#2;MQrR$SD5Ng5Y+lqd{kO#(MsVTSs2Z$JjbJcF$sy
zHUKK^y)UI85GJR>?4o8y)n=6uY)z6iwx)~C$mfHd<{j%I+c2;&Sf#4n-E*`*I6OQ|
z>2UU&?)<)5A}~8E3mo~MqsEoRdkFz&%Vy~Yh(q4IUH47;r|<1#ghL}+d15n_*gOV_
zn#KqDHm$#CytsU?!h*FCz<trIilo2dZu@Y}%exse9vVu>U^?=34tCR+0$C(WFo7e4
zDw$te+W69R=UvcXVEh8}k68xW{^pG^QFK=<F%u~-e|2AFIygUP`m9gV>1Gx7lPrMK
zb{?s0u*m7)#Q3D#s1i*ZnSgufpU~S>iN$F{+X+dnK}S&MBSE3=bKY9L4|E)nFzvAV
zxrhB+lcy3TW%15f!Ju}VfAT{+fjbP{%MZ@c^sMrUw5W;gqm0QR1mn`l<-NJUzgDZI
z$hCUCL4dRXF7Yz*OrvTd&@N@Ye{>eNU!!v8q<=8Y#w0EAW6bj;Yq%II<L*FG&n`#1
z6|F|hNb}BJJUUH5xlBiHsazA0goHVw9V@h|EN(YGU=<$S57`IQk2S*BFylic=!S$$
z$R*hWvkb5#-Z@=+@X7S}AH@GYvkzAq!l8;6jW8voUeRu_>8{~VuOmqd9v%0G@+m-I
zr73?_^KXT86@?QAv2emGYVSEuA01r=KO9971`9Tkl`L7nh}W8D(%<iJVitR*g)oMa
zDRc3}GBGxENxD*oE+k1#nbCbJknkUY=1R5h9sL^+`M>K5MF8vsET9_z5XS9NHXd28
z9o6sik6-~77Ns;V=CyU2#Uhfh4yXoC0r?zW6%t(%5|Ru+{-aM^_n$FG(?nPy0&c=n
z?l$T|-D}MWxN8H@c|&glP?gDJv1d3DLB2~ZV7X>ntthOlSa3n=ujjQk7KrlwZ-cA5
zzR#ffA}a6%x^a5_$?P{yWs+InO5<<LB1%cIRY&{R#bv|CZM;e-q$AEt;vZc|upiIA
zOI+p-lD}mQE(#<5iLrHZtrwrJ)R-$bRv;2`AsG!xuv6~~MDs>AkNB=qZcs8GQiYzV
z-F<`l0u3`TI%;SkT&__@4aopKA$9Y?_z$sR)g+;8c|socVQgFEv?j!lvOr#kfY!XK
zXM<9r8W)HhMK?bHAb1bz<Jt1pzkl4F&kkgeNCc%vZjNkROGKtH3teZgdX5+&Ue^cY
zU-OJ@HyBdiu`}Ng);IL<<K|T1Hb0OE5gb26@HATM8{9>{8-Bv#;~&Zs3Z9aO4(isw
zG5eiW?|L&hMcPKj!9%>+b}8BQM2zPDB!~nS+EaCP{%WV2O5YEM8^kNjjbk7T(eCqF
z_>eUrYMFwV4wF<-yr~X@DedgYu1z1MBhH}S2*wX3pf$_*-XO99m3bi2n&0u61s+VC
zLJ-<5I>w=8kq}Dqu&(3e=7u&omodybe3JF>>TS>EVwR=Nk}TUACsV<GELUGluO>5J
zlg<;mG6zp!)@sxr6boeW2u}gL$os!(Z9-yVAOJc};t>Hdr!SOX(_wfVQc@-BgP~m4
zpl;g5Sfoo^pI_(Q9!P3wbIy7O>^%V21Np1Vv&@UL7vy(R9tML<#OA&aBk@fewSU#|
zvcY%|R8H_E{EzvotKwfapLWzvrOXh8-~fqL$aF2Wcf$<Ud)7*!XY9^|&6k0EZLcw$
zp5CoUe0{_a3W=Hi{l9>-G(d9ym5oQ>$@KP3D*)7U=<6kTGNZ-C%?)EJ884RX6If1U
z#FB!QdOSVS;aavss!CV`=9Y3X!C{7nXtP~abUR&#vYg44N@`!3bM+`fGsE)TC{g4Y
z8l@tq<ANs^a2J)=tB&!G#e_@{BbeG2lXHfmD}7Myod3aw%cHeaqb8SQ_{;2!O?KG*
zeTWWJ{9NdnFU-s0fBmyR7!C<xWCDBgaNjK$&9{ROytY<u<`q1j<TFX{axeFqb!{*W
z`UKNtRqVAUn<~Dub3xr)m^;Omom}(P9JJ7Oc6Z?3WFf@!;{E#b3oG6<f#yg-@@c!%
zKS42Z!MS#8H6W{iDocoJx90b$H*fxAvrT|}CO^!x%b~u>GlZK#zc!wT%%Z-SJ-Kjo
z&%U%C+7^LDP7}Jxv_FSN%Q%uaZCi`)Mp5VFj{>xX+rY@U=(nCB77cMs`|Rv=8lifa
z<PL(Y0dUZ&88fZu02n9thdfH!T~7kkOD&=ULAyosJ4p$=fa{UG78}!|8ygjZ9w}-5
z4Pa^;Px6>5f-mtF@O@$gK#!2}a#}i=>XOGRoK7zwc9Bun_m3bkG4Tb!TW|VdNu7cP
z-OA^Er>xYiKT!CeV@C;RIfL7naYnViMeEr1+)jiQv=ibgy+_7sw<)Tfc>Zts!vgE}
z_MjEBxrqv;TWa*aIa^@LB~_gJ>pNfmJE;duU#z>@#uyO!{qivc-$uiFnQBq4#k$qH
zt?Sis_?*G|;VBX44XeRON)u|2-e)}%oSo~2zIhxFcir~3AD}Ds>-2@)yT|MA<NVEy
z)7R{yK+aA@1cn}ASmQF3pZ&wcsl%})`E@jVru)Ej$Qmf|kz%tshvO7<e@u>Zf8oT1
zjI4~&K&}a!BUmo}3GT9B`tRfk8LLkY2_6<DLw2H-LTq%Hs(naX8!EW%8&b_?OITGG
zF44thao_UvFXZVgZk)YDm)(&cGEEk1eU4umIhx0oEsCUOuT(FRyq4fVZO)hcIRd`S
zU*5iBpZ_j}3}8^82c&Wc#$~gGU%N)l2sq6ZnH6(+15?^<wL4t6YV~3RWoZ26XhJ-N
zXdbQvK9|h~#7<ps5()dDi07Y#VwS~G2+<**W^#|o#ts$;o$t_YoSz-?-`qbBFIUSq
z(X5y?SK0v`1A(7~4#+lApP*e9q@=0B01I%m6jkZo{)oc*ox*Sm6s=$331h({8y1$w
zV`t_EY^AtnyRfdWhRKY$c5w*_2>q(g(>WGXWIZEC*{H6=9IqYZ0aw0WnrYvyknEkD
zoGNe}h|NZpr$|s}n|A=ZlYPx#OJTfgN>`NlQ>3Pk3c1yJk-<ccu}}qqhlhTr+isY}
z1Tt{G&kDf!a)fEiBL;y#H8}nj_C{etrTPDDjyk&BvVAR|r0O!Ezx=-ilGph*zTwqI
zc<JJofs1&<pU11sPDs`9GlTwvfu3Q7t?%QD+Aqg4p9Sx+eSWc~RkIu5{erzl{lM<a
z^MNG=51__<6T<50rT$wO7_CGmmW@1gahZJUk}dE%>@;6tu=dv*>)+%yH1t+dopCK=
ztbv(?bi`aX)UGy1vDR%I{8K)-a;)!&=!tuRYr$8)-i)4Ci03A?ReG@6yILKk{z@tw
zij>_S&&tM^4;ab3QH2-)B9?^IqOTU3I5I-bj=y1g{ya#POlX*a0mN%;`TW4~_|QhB
zN0Ro5ls72&?b&$ehbXVdLkL=_REc)6V5=xd<4|pUf3GQ{{l%|e8_l*|tYCKdH{XUJ
zqi!dpI{|lSYz_LcV*Wsw21Cf0P*nSiw%Os)&yjT!?yFwunU$i@HinJXn)u~xmYuu9
z&pCZ~R8@t4dz|PlI31i^77BgalrPrM!xl%M`bS4|n8<~M6nyNs2;BX1YUKZ#>tmPb
zyiIs%WiTGPIS1oz=n)Mh7!rvYk2h46dg)RiTNG7mb7QeN#5s;U#$c?7Il8P7U$WeJ
z=vJlaJjIGx8=xb=tLZihYuo&pFb9q!5|*pi0nVL2-_YC5T?TX)Lf8&*`F{e&Z>DP>
zr3e9ejE-T^*95vcvSoZ!49|(}?d^rG>$9^zW5`%0^e9+e|G9NxpWd*dSlv#Pr!qNU
z0T6GO_)fV<qQn8SL8M!@l)_)SJD0V#S3ALUAV_!mNR@Q3^n=2HYFZhWG@osEKPm3x
zgIVe+0I_Zp)qIHn5r_F_N_^>F7in)ud><;iDn=p!DYAJUI)4p(q_s?Y8U~c*H5zZ{
zpC8`$rP9)h5<WJS-apdjKeb3g<)US~<t|v5n|^EyrHyV-mml!5-xu9?=h!iRc;d_N
zfm0Z^H))s4b^9PHm#g7hVvAzRxGXFunvHcbPXWRO%Y*@SIS9)6WXw6I&xwQy+>(;F
zu|p3k*Xl!8Ra?9PAirIkB`VOy-Be2(LKwAnPaE~3dqWlHm#c8J#WKabfyTaca^37$
zq0Lq@Ats$DAy`Y?CC3G<<zPs&3X>vcV!8%P<Ee!~GQh6CX0p01j`ujRxYl-zW>TnT
zRMa}yN=)N?<i;p3OI*299tj{Y(dM=#p39vmM}-I$j`X228E%qtqHrZ&cL)$u#zTj*
zZLr&--t}6K^nTh*ig5P4EB>=r7cHQMs7oz?_3$9L7few^LXab9JTC;AShG*TSRH5Y
zHa1w)#tF|%6Mj;ez(#7~+x?EDl+@}my%}~oqjP$f=_tx8J@d8_k)74t4+xv(%243v
zT#hif6`U<M;VQ@H2#Z2AhCHB-M@~+`>M|r(uE+OjJW{5d1Pr~s?ayngP6h%&(e0(u
z59#H_Vm8ZE)UQH5dF(p5xQS+uZh$TxtPc)s%w@oIluSyy6*rKtG{|Wg%AqAoj6#yD
z78Y>*R*1SSlBE|LEtaI64_7RoOBm$W*QI4*zRJ1;F%s+=wlOOb2|x%Cf~qgLc>Qk3
z!i4WhU;g}wdQ=$t9l)HjJPr_T!;LOe%TrjDVkWJ$?1P_bk0X|kk9O<6{7bMNRyPs4
zytG#?(nM}{*aY^2Z9&{r$fHUmU*A*Z-+4Xx3Ja4DTMrMj&<M+h3I>no9Ct8ZjGq{X
zMmEXsjY$0bgm$mb!xqcpK)l8DK$rp@*L7L%A<)D`CTBpkJrE|5ZdzlCwj>=Z2|?lC
zbOzsI(1NOlJk=mfwSnIKQD&1k?XZjcAEHbd(Q;e-RwG+WRPj8NbsaE}d4&q4>sufU
zHA`64N6;@Sxyv3;B1bwB!>4q3qz;zXmDGlL({u;q?UkBU_gDXe?ZaG0V(>FqjUhXJ
zyjHWoCS;TZ1^{MQ0O>!!x{3ql&ILe5azS@8Pp7m{98lY;^A7>%5GGWfJ(K?i8c#4_
zWv%oDeEF<i8Dj9wcYm&5+^LxZv^U_L!{>{yb6PPr&PGO|C6(!JtbQ;s{1w*lL-yoX
z9cg1Do$xbOiX><vg}`cwoAu<uW$DWyz!nqGI2NeDF=3xA*?%YCvN2koXpx>>8jz$L
zN>`1&w;VvHmauEv{x;;D7BY5o4?Kw^TY`e2KNjG-_#=2dVYnJA;R?J-ES2(b_L_1Z
zK9{L*$DGe@8^=1fjEUi4)g#R{s(-K(+;cFLo2`6u#euBMljKGwToz9!(N``L6+a!X
zR;NQl(a?~Nito=f9YxPC4zCJExzr8a8LHsbTPCRYU4`g=*h+@0A&I#`oFC)xihORh
z+9dx>S3!^?^bKKJx9zK>PZW{{E53YVMCj5UyTs2eMRpR+3U*v~vW_ZN=>nTtiPH3Z
zI`fs!roAT`+O0~Ktf-2Mrw<E=@~3@BFlzpi@I7lIf<2G~x?O(Pb+X2E{S2S0rxqE$
zb;-KI1&{0Th%2pQ8By3xk!%6-uH_UuHRkO$)t=VY*3AC|U4-(YJ0-*!Ln(PvQ}O^o
z3<F%BP4|?8E?A@T(Wo=XC5-Ye{y~Eew3S{wz%znq=>JNELd5&?)gcpM_~tlI%0(5y
z|J|KrCXX-vC8J8a#RvJp8-}vv7(Or?%D$F_@~<7yg>s)F6sN-m5ke{qaEnjM?7;lQ
z#bqjfKDP9IO;I+Is<?#cp`<|t)GSF0Zn2J}R><z3--dv{m04@I&L%okG8obW{Yd}Y
z^ck4z<M5B<$n*~nV{hc>nVFY@xY$VIm^}c~z;~@?4n>kLQGw!N<h<>TX#2RuRy`2O
zTv~R<O0^H{x|X2CigttDshJfRC|G2X%dkh|^Bwv@Dz`s^UN4$r365|{7)c=_OU6t0
zJ#&>ZtRBP>{Zsj#@bk7qy**O%4c~nAqF(gFjP-i5f{42YC45^(mS5x|qU%t2lmg7m
zEXHFnkD86r&P*0A?ISx%2%&=4vl)gNVpi`DzzlC$)l`0ohCaBBNOc_tb%BEQ^uZ5i
zYAY~*3~Jbq@wksyxyJh~T|Q-2o7>f6r7KIL*7YYD4{Z3@#KxAS-1HPl1j==c{U^uc
zcOWPqA$|!CMq%yz&Z65oCAhZ~l$%TJ^KcRfAn!<uii%sxNUr%m9(?|zvHf2Uaq(wo
zSg}JDbX!f<lc-KMss#MHzx|k=8p*_*5xc2OOw6VD?7-|&u^qGkBbr+E!+Vn3$;Eke
z-n0x2-(9D4k(^DkqUz!zSGmfA*bLFwlkYA`p2fnkEX?o+DFKglkjJF}!tDteX@RZl
zopO(b!o@}xY380M(UKx-)T>fHU$6#))(`8dBRK5eYQ^QzO_<D5`XXB`w9c1JQX-3z
zP9C>Eqm~JsZhji5R}ql+Oly8+plTi1gV)HQ${N^<rBtez-@6Pk-$~Kw)ww%Rm9JL}
zAEb#ZP+X)IL)!SMXvz?B3SjV4-WH1-YKeHb@$Tm+pm#CGGp_R(u!hpUygD}u311vF
zvTu=j70e#LKh`+i%v!1ovL%aSn)T`oi9l4EerNyiAdHSoCJs=zk;`i=Y}(A28BL%{
zeWxl(?;r~nOMB<SwO5vluO2sJx|RdMSj@{6kTx>b=f)ywjBy;u9@C^EannsL&s9UM
z(QX9__8$C7s~C-02xYv7*WDiYF)6O+5~e*#*=$P#`<4Y9zWvjdQJM-+HcH}Hv<}It
zv23Vez!g=Xr-x>rPRAx-TmkMkxm~O!Itpe;k=T;D_nAzcqHhQMyC=o>1rowa+Ys`h
zKuFLD$@@+Q39ar%4xN`~$b2(x8r}Jd6XoJ}^udxkD16E38Ck5S(|vea-#iCFAo}LU
zo_#Qo?=c15rU_9w?yuE$VJMo1fDtSH4%5uM|F^Cpnds7bR}4taIuXS<5+7MZs@`W*
zI5chz=e+}KQ2m{eX_2Ub1GoR{tL0~C*nwY@a#5|zRhr~fY%mc1+vS=)INd_u=G&bK
zL!>13AJ&_ANpYy5@rIkh!!?Y-x=zZO3yfx|EA6_WI`0#OXqu69rXJJFBfuUZ3?;X-
zzyevTVcSO!d-b5NbsBf?18F8Ny3_@3Y|$4)z5<^bIz-5Kz$X7<#-`dBv*vt4#P4|)
zX*xP1nw^W78VvQ&QBi(@{hg!infwQs_;Xb2)MR_imY_Z8IPLMY<7<BQhf3Bk12R&u
zMou&jKVQ2%mC)fsPrsFdi%}A}cFBVDbq&|=+L&c*8!jcBY-QQm7C!lY#(Ha!{0_Hz
zD>_*!>fXsk{KUkxke7B|y-p%T-&o{-_lA6HtAO)u3}pUI9!UIfu(Nm5DJGNXyIw7X
zBSzH#X|sR^AjR<xm4l*PNh^h`fzg39s24Ed)|bI;pY@RA_b@ND^&%e{xaZInagIn=
z(HigmT{(TN-kGD*%`W^Rhw<RxEaVfi#3Q&Rv>sVfPacWeemg8=$PAQc_d_Lnn8_Qf
z0ut9-YH)Ctf}9;=V~Z$B4h{)PBK=ATxOl>tmKi=ZWw*9om6&ZRBJYOe(%7g>MTv)w
zjy^UumRQk1`}A;@TD1n~^21QxP?7dFGKdJn?~i8+zc!WL+@Xlr$wP8if574n44OZ|
zB-N(4{Tz{Gy1xV#ZlUakaNt4o6LS&&0Ug(IgN*wwdZQXKTat^^w3I;X55~dz58nNk
z$bIc53%bHOgS0%Q)Eb0s14SofC#g6Us*M9Aey$qCFFaf`G^fsY7v@V9x}?A-ab%{Z
zYxnF&SX(qQR+t?qWzgwt4C3?WhtQrPLKk<w*L9+Uy2(9+w7Y>~?TV~SDrFJt@fWgv
zvsmg$BaRkte*pXdQb@2><6`K|`N*pKl@fh)u+0_II(TMpc(tf_$*t6`U31*3^i4}C
zSRH+)wGu#UBp0DDA(8y&@%q$Rr|^G@&7uXMBwp^a4V1gJmx?121#UHHtN)^@HRy=~
z1cKub{+cI>8QqdO$ic=WjIPHs!v*5uclQeH@i6Mx6G<G)+AHzK*H|EJ&i{hXSf!=S
zE3!<Gkytg{QfX#P)_Fll1n-o4dnV>H>zA9YMN;|OFZXS~Z;k}65r`8aA%gQojik+U
z1f7v=HESeI#JcCe1Z$fD6Y8q;a(e+7ZS@fp!DzNvn=%^X(uH63x+5l6YYPhk<W4{#
zdXoGL3(3Yyh_|}qq#f(v9DZjE1Cl(kcLPxa17<r;Zq*cfaGwl{*ZuR8sM`{@gkFTi
z+Bjl6Q4{9d6S0J(PZ$x5d6kOx0BXwE<ai=o8>0%m1u>%9Ki^O;qJA@`8zY>bst-x^
zl=0M&1_W-@X>Go<4mt1wu_*`Y4bw+Nw}Jfz01L-pvx+d%ajznVbQJZ}8S~utf~{q;
zP|)BkZs5QlM~Xc7vp3iI&jEaKNh!thHe$F^NukSh)|evZrt81YHp{iq#l?6XeY6rk
zM>Oq8Zm1^rvW9E;^!kZ(<#@1{wwL}LW$3$hvfg`uxxvOMbOTe{ddWHA>=d+gQrWU}
z`?=US@m*X@8AvB3kZ60B?vlAgpVBFxo?9|(_bm1?>=I%}H#j9r<~pV0;*<N*v$87n
zfGBNF@3%KaXIIzg-sAtml;{%=5#2yP!sv9(=5~`fn&u#T;sD<6iG*?lqM!?iv-s$E
zN0Nm_Mc1|!+rZsj{i7rc5(C-w^dzubz*;R64{(;bZ+K(53Jnd5T*%v)MyY@H%O_xQ
zCH}n+b!+RF^FOiAIDa2eYxO$elG}wdT}xGKH3(0z`R8fHtmexD=9?YzNURo`Bdb|G
zcKzBPXp_px!`FdS(0sRsFRwt<Z$5OU&pGI+kU=|Vdk6?O#euh(*7#y}hM15-sFE$<
zZF%alVw2+)VlVp#tF?6jGTrRx&}f{=Kr5I@Bid9jgf5{j-MbZ8HZ#*A(HGf;HY0t=
z&<>&+cagLf?Z9zxt){hDVkc^&KJDdN%bKln^ySm-tz_9ujdGKLxO&wFo@lDy(4VWH
zhlpj)2QOSXeJRpcs%zF5!#*cYRO|?m<FRusmP(9&{<2V(SQ{^8%vGsCEuqvzLXFOX
zXxl5TY*|3x_n8V{D3u>o+b0t~%Z&xOCuHhO(ldesRqHavneG;&Gu4mC3DX{|ju5Pm
zGUZiS7=Emt8oO%|np*|QT3GxDH8;1QU}Gb3Ufpy4w}pRjQ2cX!9G)bv7Vged(!k=g
z-<DAIjPfv$qLT7BTRP2tBX<%K6l7L|bdwF4NpYkV9{|Rk^oU&A1(<(<gKp`ecz8#~
zA!7C?g_0~)mIWuz!-r1Hb;`2!Z@E!19epNsl+=njwDB69wTk(|LN5@GFhaP(&Q18t
z2E8$K92R?Rj(r`cL4a{O_SUf%p2g8{t$ZpJ!fmg6tKI_Hj_6W_shQvI;^M&cwY%Ak
z_LNg|QyP`b`=1+3?gN_Yl_stf%~FjnE^(KK*m4#ZI%amrsah#HgOHk!+bR0%KYdtd
zE<wm?Fz4u3(2<ogmJnnar$)uN%*}&acy^VLje1=W=IAUOL}@ZqrK`K-``fjwj`77@
z114Ey&E&i+OI1<5hKyq|-;;XXY$_dxtLuG2X0EM=bQWWYRmo4TqcSu#u|(1`+h*!>
zu738lDMsHCsVoQEm?KdGkcK$xRe<R(?g47a2FV}6h{q?fmL1u4k0ZP!wWghOyYRAn
z>!2_NvD+(4+k}*)@7T6&JCUPZWX)hQW=YBc#VOZASt7e3ej2I~AdF+(Y`3lnH}2Me
zIyPRC2$`yycKWzFc{|}|iO}?utL$^r5Xzz~ST(YOmOjJfypofhd-dY7#UT%pzo$Qm
z0NG`9tXp2PrJ6mxWLm_=1Y^&{6o5F1m~(pQW7y|=z0GrYiK+h01Qo^NEQ>=qaWVbP
zBRK&^;65>8RE%;^?neir2a12UMM3btzdaKtB_$pFc1!0190+dL+qpfh@*N>00SmXX
z>z_}sadBz#pR|XoAI-mEIJ0!*XBxDVnvvi%uY=vJKGqbV0ebLD*YgR4uCEj?UsuL(
z&Ona)&-Gz^{Z7y1OstCwA~e+wc1=bd$Y90L$^wmpPbV=CoNJrqJ0}O<!7a8EzisCW
zLy4LtGGPVvfGX``g=zC}-wDH5efpxyv2XAr^k2T9BS(u)JuW0S`8y-Clpfk|%L1Po
z0yv}!dWjtkGmE2%(ML`vCWQw!ARW!^i#P4bz#bxcRD~_3g+h;+{iC5F*+j8MMW(J+
zG)y6*%3(ZEgVrh8w9{aI%BQDiSwT5%4aSoPm6!LAXbDKkmKh`2RHaGNJxBP0X~-Bd
zNO0K+XVZL)t03TmIfElWps<LAf}I?u#|L%D^Y;g>S`FX@qLbMF`T{5FVCf3EEGD*l
ztc86%s5EKguy8Ibipk!K^SVw}9ZFKIyn+z?aFb;w&+Oe|y&@RZp#fG4&AdM#h&}RO
zCulXoe&E}Xr=%(-6J{exXORNnEdw}DsU>S=Xz%rga@}A0njxFbG{{xlIYAbi(CT%+
zw3#PIM@M<B7m6)R2>cC!6P+T)@POg(czcgTw88H`qfYzc)O6qXI07yN5D2uzEC1TA
zY}4X0Ck24Te#0XpvPzmd$0JX7cbyCZfZAHn2FQ^3+HW+=pzwP*JJWfP(0};w(Vvx0
z;tQIU^QI@GDR)%H<fqC?olwJqv_IZ1oFw#nV}_$~`oF?01L!i`t`!9=e~a}qo?@P0
z+`bfQk@=*BDrLBO9f<UorIl+UlLP~D@9fN!L=nuR^TUlwaj9iSPoWQ{BJmdx2gSq1
zDxytG?85`eRv#%zTx&TI7F^$VdZ*`yFvU8w)zL3z-e9^dtRp<|gj|(o)u9MI-O~Mo
z*k{6Bkc5wm3xZxwZeq4&LME}D-K80yUM5q&8S{w|-AJn8#g1kMtd$OeDBS+b%V&I>
z+aa~V;k&yKTBZKH;P8UgBje$$)OLdOh%F+*3*IEi-=BG!ZGWLXR)*}pV>3Nn3B_pE
z^+hS_ZyMjH>Ca{Rg+_4v9C3nA?M8+Z@W!(jcn<DagT;@;cfwYyJQdkX3*jn3czk+d
zPoLAEzi*<XHA`(gH}|tXr*#eL=*%1^x-yELZz+vc&g$s~+qW{-5fNerpU9~IlhL4T
z+!{}z7vGAZr&2PiuPhdAQXY8-{K-u0jbDA?Zb|Hvb%>Fvod;dotK%Or{-20VQ@8-i
z>GkeVyUjuWAG~C|hhz*MNbZ7tDmX~6u1qm^066S(4}Ezlyh6o7e`r=pXv!aFEgP`8
zmcb&ed6H<_FA8?Mwffb`#Unhp1q0kXx>BD84jZQdZ;hgUuSJ^gAJ5A?+D$f8kik$8
zsiHYmwKw<oflXCSXw4*J3r9wiX*FZAa#E=~MyCza9C&6LRo{G{_8Q`d(Y)y}X5Wv$
zz*S%b5haU-q2eXb47>aJF*b6rC#GgHKZM7lwOfnHkF!IIy&oE%A2C_2REEC%C9~pa
z;dMP@+-P&4K0*#_%BE4w=MM(#FkqN5{1TCt7M00*YT!te4HVz^xYqfR5zVMCcd83-
z4-fL%9Q<Pd8VE*EYXO6LCb6>VInXm4?1~D%>5E=7dq-O9m)mRA88GDrP$#35DH09F
z)d-*yyCYj$)3HBSZ>*5C8VK{cpCV-OI1PR`;9}j+&Xtx`HJTpzh4-}de*mIEUB1(z
z9S<QpO$$4F6GCcxpkAFo95`_tm8#Z6a7ZvNYA-@>G*>F4{*ppD=!SqYB~Unq!4i%@
z|H}{s%V06{)LeZ`I(m%;%iyu=rF}{C>M4_jSl_s~XhcOuiT*wcSt+ro66lFb7vhkU
zaSks$(-CeOXB<vW#KPr!5fz<<j7%YzO&TbTxo~s7w@=PW6u9D|p(<?^viSITIijD0
z*Zs;fS<xYHEw!mN-j+@r3P+$?_O~<Im0`-7YuB#H<B?t@YD?-f=vcM4x0jC=sXw5X
zx3{-^kq4H9>;t&igVP~0OkrrSReVBxvENZ<q<1Eahqte<O!nWrO?xzJ+7hvGF)~D<
zQeY7D1_hoR`V?0GyA)^6oPmRz3mzXl7>D=n!==beXw;+`YSyfaeftlhUc-j4S80%x
zn1cAYSeYl4#ALP5YB+S@ARNWbu0{y7oIJfb6_*fLS1w(~#&sL;`kViwNK;%Ee;*Tq
z)zQTZJNNvFBS()xmzyWOv}%<Sc49p#&X)QZnv#+uedFxxBBok-GfgqK=BJ?s*l1MZ
zckN{5v!ujSq@-p@kEQj7+AQ|2m*_1lWKAUsUYTE3h()Tp_T!v6Qt+NXa}GH<TBwBZ
zbaHk=tCnq1rFtc(gdkTb-G%5)#f6ASAyzYB$aTWuBZtJzNo^U5_{-d1;NakegcKdl
zoWF*w3?q&m*^8jyC*k7eh4i#I7<4+=ir;k>H#0Ift|k4K)mv*FbY{Blgg2-5GMG#G
zn!_;6qL&8UQU2W2lvE^(<0B^e65?Vni}lpNUfehYhWemILq9BCbr>g4XJhU!8=({T
z3l}aYAtjf>)6`=5I=G0gwsGUeXw|B%Y?tWhXe!lfx^Ja=)oOJfU33b1PVN+np^J)&
zx-YSGj{+38`0cmf%8}m$ovg!$4@dLn&AD-y`wGR(?%%&(ibL|!76)B4C|riJs8p#^
zMZU`06NdEkbd)w7BEvjPh#Skxw<>OuoSKYH8#mqXIX$lL)w?$woE%~AV2`TRs-t1U
zW>~X&9ipy8qJG2ruy=IAx^<g{=rKvrSffS_nJP4w9(5ZHa^(Haox5cD+O1nQ;02)<
zotzzzu1-f*Rt9{1z2WKR3XR4VZQ8cM*|4*+`dCh4G7Kg~zA)RfdpBMg^)hT!^gB5?
zcH$(Co;)o*yhfACGQP_w#ad2|5w;o|*xB2O?{nn2PC}JZh*2hmoSanoIG(a6P`_nw
zuaQDnsWiaF)n16;EM#f(pp=8HECa|C3QJB|#SJ&|R&iU<!)q14W^bw<d-fg@;#(nO
zUTOOqH*1WRty`f@>yC(tk3!h#ldu;z8o&Md7p`5)g;C6#mm$`{CLT+dufu?@?NQ0!
z8EM)~M8~<qpif7G`ZbY~d=2MLpGA#2jgc+3D<?Zw=s1%(FR&#8gi2|ybY>3PFv|Dj
zv6a=vjK+K?g*l~|Nv1$E=uARDrwcKih?py}xN`Y|xDhg-WwTm%V(8P@yXz>T&TU8K
zAV*XV^uooM80<Zk0HeVMI+=+=3m4J0p~1D#qGc0k^*Wq7d+DAY>m{mJUtiyIl$5+Q
z(1A!7H1;f(o{JYR;`{HvmmVjAMtQ#a>Z_<+xiU8nb6=oN@7S?p*exzBVPRo6cxvf9
zCo$WgK?BsOQ%5Fd=Yft4Q@+q>G`Y7bZjzdm3?t=%EdqrU&?D?Rjhe^-qLo8yK$}a|
zv-B|O4bY}$;mH0&$jM5Bo2v`{Gi(_0ba~jheJ4(boi@j@ihtr`qjBx(6;!Dfip7in
z#^_Nap%!A&&D{lFKE6;3!IhnvEyZY1Wk1BlUXwS~I)g%%hSdvEmY9%)fByOhaWV1Y
zFEw(s<b5S!tCU#_OqP<m<Ym>^3c;#TLaWV^!Z{;T3zdzHu*os!b`|SnZ*K!P7Y8W>
zv$Aub6~9gKxb}87LbQu{^Kzl55CzJeK>5sMW(B21xLPWhk(X1U$nOuW9$cfz?C~{c
zSD*oHHnLip$*4!oI<+up$PhGZ(;A5}aWV{|Uj63K=NNE!=XNBfiC@te(Yd}mlC>Hf
zyOM&43uke)R&8-(-VnR@>_kSEqY&=~_<Adac5}hSbH@=9S`(gLJ}^<Uh#L!73Nz69
znMC{QDGWtvZZC?dB`+*YdEy2n&r<w>gs)l%XRQo9OG(H;Y|Is0h`4}+s6_ZzwiWwc
z%$Jvr_{jZmw-ZxaJ1kp!9{Y|*32{yFx<cFvG4Jebi;$2&A>LcULFs~{XD;CIvE!&;
zyNPTcTU%RG?b@|BiD~A25x8Xm#qNIj<(J%}l#+e>_R0L2H2Rz%uNVy`<5Ahn{UAql
z^gDL!z_xAM^0ReVA#VhEXeb7jyr2(TzH3T@$mtLnrid`GwMDnS0}y^TEdR5gfB6~P
zwr;_Tua1VjgOd;?c0#nC5yCJ9^&2&m8GSBCU%{~9|HS~`0XTf<Fb*9)jFTr%2(g+a
z#ip&TxoR1u?>e~u03Ltx32a=y8g*(_gR7?pJlx#j<miIDoLo5w?UE2vRPwb$r;czu
zd>kiEo|R(KTs;d|u;6z&a80kzli?B$_72i3o2ku~MIxlo6l#||$p)he4t5SQg%&+(
zm*UoF9#AE-C#W^@sc3p?njB!}=-?>F1(2w9b8!;$>yWL@lL9$MM?Ohw>M)ZfSr~2z
zRVY~ftgy2{%3LWd+qLV6)@>dWTF@3=l~hPeNri*P1`TS|!nWnhV9d=%-|h|ZOz$et
znmq9Ohkql-WQW5i&Z1M>1~?mjUWok+<mEc!?4?v>XQv8nP(v1lXw{}AvQjcEp%*3?
zXgx&RDW%8OT#MK2rG?y1Sy)49t!g3KQQQcmB&8xD?i!-5hU3cBXmO*Fj0RQQg!tEC
z*X}rEitlU{dAM{n1=|mvM|@H)vNDZQR697CP_t?XI(6&{eVzglQP*(vzz(E{8z7x7
z2ReP0{3$OlFXOmz<GPjkaa__DTCLWVyfoyAp}0Bb{zE4RmE5JlWL78~f$G@bkF-Y2
zqYdS4-MDe1^w{PU@#aub1d3awfhrI4qkZbzN}CRmVIC%;qob?es<;Ua<kaP5<^O%|
zd>AIYH6Fcsb;p`jt7LiIZryvLWs6q$dH&Bb)mHVIHBq;29i*hC;P|QIh={y|_}Dn<
z*`<83BvdKqD~U*>QYpviTsU_DRjO3QpMU;|p-(>zPcLs7GC&o{!q1%+e|w4>=$i1a
z6pYsGI^p9f)1;6lQARIv`luC@*VQD1u^qCqGo>feXfRkjxYojB3RyWVGdo+Xk1@YM
zgJsy4959xamM#RajTFHOapRtyqm?)GPLB3cILmyxc?RT(-!xk6l|_YX0dZ@M&6U@3
zg>_xbg4Z&dOL|jx?A(hkz52k(#!hCMuob@@aV89UA=1MmE+RQC8T$^Nf<8M1jhl5u
z`}Pg7dh-cHUlrS{uZ!U?zJf15`&_KA5S;ri!$#=l0N;x+2%%rKav(gsybv23FTKZk
zMm;ntjak@IXadFL>dlqTluBcMieK`ECnY5!Ch-ccMa3g6DIV2p`JzMnr)12qhiwdk
z{2g&7EE$p4((&cIb<o2GI?9DB*27MS=qlB#qe+YAaP#!U#fw*P<j^U^r^G=e+E68q
z2oF~sLVWLS$Xba4H#s@EGL@AqO@$x2YoHWC^w^T_u9!P(yPtplSw0em<<78g-@fS6
zrw>2&W$r1|snbmr#n)P&8pzH<t(JKzJ9Oy4spuHS0^R&kIy_3DMAPC1Sw2h!NeBlU
zC0vkfadu^4K;K^I(XAc2_w0g%Bq3@pMPvKct$2P!sC;tc>gI~7A;H+TZ7Y2J{Lr*{
zbJTCx2uBYd!l8ZprH4~KvKJ!PXrTPEYAF;C95{d{pL_zV*BqBIwLQA^gjSV>1ABHO
zJ3SelJ9mMPe}K3Es<ChXVd!#mpjMiTJ}68ExKNfAjVizWU0j@znVBVX*iz8}6sS0s
zlVh%0rcqi-l9>!Bpn#=UH77R@E{+be>KJ)~X%L#NjYbGty*VE&{kC3b4o|Se;@&Eg
zg5}fv?73EtDXB^N^xXNg*u859di3gryqs(#UyH-$_3Lr)(0*KqynwuPAwF%rkn2(%
zXD(-;clY`@cJwgfQd6;Q`yNc1^cLzgYAQb416zBI5U?in?o}NZ&P3tNsS{}3sWTiz
zJ5go}4ebN+Y*VZ)Rg@F^KxrOxCz~UWid&>*ATcpPmPWpG`667!jYCMFJDN8LfV+zw
zoD_k`&D7)g@i3%j8j(uP0cVJv1C2?G;7WdI-l{cR+`Vx2TqHJaJ1VXz$)Y_op)}^f
z&jskvt`_?Du7?1Ba~|A`j0}ai-n`wWO`D&cot+czxxg(85)%_KYu2p$RtB@8K<)O;
zH{VdIHu*PsYpE(3dzzSg30;KOtXYG-d-oO+wiHL-sZ%F(?AWoyv_cOnRAgfI?AaJQ
zb}WrM;DdmX(7<TA(W4ig7xbd{X=!OvOl4<ho9HFpE6X~k^S#CzgL|{5fDX1w*yNfA
zj}9N&M`)KU^zPaO8ao9#v~Mj$<R-)?rii{`4_dZqg;gt8BIfE<`S`!3xCvglX0;rE
zR;^kn4)57-iA^;ZfuQPTwzdv%68(yUgCoveh(M#Jt%ShchZaqn!N<!J>8UBWaw$qI
z&w#^+k747cEeOAGQC1&QtCdpVQoCz3YGh_*$YKtLY^@xiM&S!2bg4YARclgsgiM7c
zUUuTQNs?x2GxNo*ImkePl$12sYABn5Gwhud$QCy*i7Dwq_~~TW0xeI*r%JDMfno^?
zMZSbpm<kKsf&#eEX9}wq+K7LbEJcveNEgpuz~+q`5E~OM+FC8+gaa#kpl;pT@bLCS
z^5qMt<QagL&1z%uiVLFuO2m>SE77`jTbw$25LAP~JID=cl@PNk;KZ>L2(D2begTz{
zA=*<d3rpn5xMV82K%Q=uxOt%JbID1`GOuyWwW~OH<}{KL;t=fbi1egX><N#Cm%9OV
zYv&;1(najueF5R&sYs{H2o&|8&xVh?E84Yffq;-II2&~hJJxPSTug%4A9k`joI#(1
z7L9!H`iRGnm94{pePL+S$PHCm%fY_NrAwE7DsGn6+!ui>E@ZKT1`Vok7qs%u$&)AX
z%P+skpl*WVY-uprtp)`!%-uqRH`cCQi(R{R6%w{o=DA0Y9x`9!gGk|ZKcMZU8_I&)
z%{)4g;Gjq4l&97DijIyph;u@93)35i&))`KUS5$8dYi3T6mGt8dT10{`F_LJeR%Q7
zX1H|m9O^goL0}~xcze1F0hx(o$B&{>vqlIB4uOxiH_}p*<-n}Iz55^`F&V4=U7jxh
zWw~0Yq_?-dxM8kTDF`+iTO_At%8U%;ZM-H#a@*D|g`m_T^3r8|_4PN%$kHN*G9w5f
zNHPER_I7e07-deN^jhwo9^&RB1(dEfQB3XZX%Jb4Oc6!{!YIyGqp=YJ+bA<EWQp(G
zJ=}pD$nVU#V9gc23_|$P;4*S+ri<Ur%*uf^MptHC$je2J)|}Fd1gO!RL(39zV675%
zUBp`Ba7`#Ic1<$8K?U=mI3un^UdFT!rikml76#Gwwzg`xi~hGwo3`jXWDw3DJA<_J
zRB=;ak3Safz{<@>p)<Kak)y-$!$(oo*A4zYPKb(0MtY`$5XoUeGx$L5kd2eak0GE^
zW%&Bg{z;N$dP#7S_{%fs5gr*K`#&1=cjd|@u{ycp7;%B0k1ZO9*dj761>1JTWAU=x
zaNl5y*d#5|b@Y^(B)%T*qP@Fx=>jjmN{Ee5!?KmzWN3<tLPt!wP?@Nqb)cx<dZ9rG
z^z+1D%g@5q{V|-nlz~q7@K`TV;F5}_i(6@+*gRUs-NxuWO6kSu<XN?9mGq!l@A7ys
z8FMe8j2sk-uzmaXLgyMCZ<Jg4vBw^(@Uh+$c2U}Nh|I&)&tAH83Fpq8qn9ZnBEpnQ
zSL(v3ZgE{ppi=hYmFnQ&K(7><ieo58+z4hDbByKL+S+Cr3<h=U)~$bi7~09!(FsNy
zb6DZPF4cul(INiYHSF551y>WbaB*>jzn?d*T#Lj0-FwllV;Ah&whe7sv_xdYRqWZl
z4N*~%G7i+gk{`0NvyhRVE+3T-8uAnp<KnSu*$S$Mi^rcFf|DnXp+$>U*uHxos#L3i
z_@s2GG!D3OIU4Tb{FLddltx+YjGR9djzA(cB{c<(I%hc8JIU|@ZB8a~^;!A(Y2~AM
zS%Q{wuR2N(FohOSx-)MtPb4R#$b7GIRw+JJLfGaZEh|@sEYNZ&v_hY!lVO8YD1yYG
z&ZHMY+d;;$nxWVQljV*_Ss)*-H4fJVt2@~usV(JmE#7GHcS>4@bpQJJxZ$x*?a{Jz
zTPVc3HEq%w{@zt_aL;C}KfF)eXq=TH6K+DhYK3;p%~RpvkwfS=pcnpJxJZT=Trz1;
zt+o?h=+h1xx1K`yg$t<Dpb2uavym;fg|bm(CMV#MxS`m8@DQ9GY+(|jw|+H0c>6lS
z#kC6J;=<tXrbV`a$`fBfVv17SjL;(hp+|DF;V3Q*m8*uJLx=X_#={xw*KftuYq4TK
zXrVUciEYb8)0)nBqHimlxsZSb%MN4nj&rD2w+8$w)kCh*4SJpVRP*rgFpeBKa)_8-
zzApl|EFkYMd4WrF0j83I6!TY+FSO)An?HZPOo(lTyk<{5^%P%tnKFki5F0jZz}Br>
z^UFM2&)1$kdp;7v)(V9slr|kAQ~vu`8q09%)G5=23m1$zIXSA5ys$!yn8XcFgr}!x
zl)wM~v-ckGab0!x_?ceSd$A<<US(VE-LcaXrzZvigwP?dz_R?eu<Q~R`0c_13#1Sr
zg!JYT_qcbfShAWWS+aWX)9e3!zi*yAb|jZra-8IS^O?+eH22MW_r1CA-0wZ#b5cs^
znQpqF=UVX_Y5fFDY-6ruZelQ6V78>-A3nbb0Ren^1ZZk(Z9->XIieCW5to?8z-H_A
zU1)A@g3DzW_pf49l$F3mbOE0O6UI-#ij}LOHySxJ&ISh^?VQWp{r>y#I^38xYbNUI
zs*!i<B<{ZZPR<HH^_}lQqZS~P<i|+ER)A51*oNKdU~ViIMhSq+99wbvXaz>2(ZMCa
zCqmg$b|@2LnAvFJVp%Usd>Qz7`)v;9P19%mv@;<&FX9DLTYpFgmJA|XUJn~a$iVgj
zzgEo|WTOD=L|qsxogZ%cFpwn<MKGjAdqFEV$j)L(332$xAAS#`#*T(sZ$$I?TJ-mH
zAu~M%%_*sH+B`6b_wTuP8XkXm8GiHIE!dOqM`L?GYz{RRE?SJ8yAHx=Nkwg451N|0
zU@@6+CO;2t&8>*EngytIi}TQdj^;L$RaK$0wGrlcBUD-=8XM~{XWkU}T=j^FQsGcR
zD^BKBqQ~ZiFF+h>kLV`>glCS$q{&kdlbDH9#|x2PR0NOLAt80Y3ll~e@r8}IV|-Q`
z>|G5Qy?886oG3$mhZoQMeK&FztU^pm1ay!lQDU+f%+Ah!<A!B$+uGX3eN--FBrhhD
z^51yl4F<VXT(x-d;!m8WZed{|UVQOI*ld#g8!ZJt_Sj=suwa35XHsHVgPeOv6@h>)
z@d)K0X)ju7A&#w5464K@A&4(qP*6awTmI_mYIRWZNmYesX9chb5M^M(gb4>mjT&`2
zJw5%jcrG*=jeVcwzUk}hi@%b&iB79WeBv0?R+Xbg0NeJC9yq)jXpGV5w>uDM??A?A
zC({9@&YX_Q%Ck%>&}yUtvd13#9HOG4k(*b5qM|~01sJ{Kj=RLYJq?zKD6GHjHtczC
z8@Gcdh*hgsqP?vfvu4c`V7N|zNf*mjk>Y`^--dXS>=OIr@wx=S(<8zf2Vc<7ppdex
zUVnfyuEf8Mj*di6R}b?_)gh@bTA{LuiG6&0f&ju^0a$|!a)Wd^ge+>gXpFYQW(R)s
zJ8W>f-29p{#%h&1450eOHr$BR#jr#fQxI5zONGH|%q}v0kTba<`U35<%;UE8^}sFq
z$`X^ng>{LEE}ShnjjZ(XFzHCbtVaNT8?1&1oGYxy!}l)0;lgcjx=lEIq6i!AUWM|C
z3USWtIA5#B3ombnL1%`=5RL6ywjw1p8PlgvLqmNv8}#%Dupb`@Oh`52Sbh^qZ9eFX
zc39L#oGxuaO^XvwFHI(bV!{x_*o;ifU$lxH-j3%UN5#$~uyr{@nz`axB_OLtg&#ik
z01~2A*tAQWdzUy)XP4+63w)vrTROz{)Fwp6B_Yx<vedUB0j{_pOxNo|Ml-9IUU~@|
zH*Vx*z^e@c)mye~VeL(tHPH-=wnJGbvZteBtB<>q00E5GUVDuTdgP#q#8<xZ6{R3g
ziQ&GX;r;jDXC2#cxi2anBkt6iHEUP`=hGPUJ5=NlKN&%*5qWuer2gTrs;bh2vS%03
z4N_B6OD0a7xK}*(5wI1LyDp{Y2Ad4qk$d_K&Xk^m%kAPNZPM-cIQroaI$*Zg1Q4>|
z7BMl7O-#ntE$?Ar&H{1oO2^6k0x{0`@Yb7uhP{v0v^|K9i9zo1gShkV`|<W$Z$Yh*
z%o<z{iAPHr*_7l|xCLk=tKa6PTBw~G2C*)u15N=>iQd53RId+x{dTy$5{)2aE5?{0
z5b!Zim(f8`TCF0=6=m@$<J%^HIekt}lyPwxXM_XH(e;aMd%Q$NaIxWm1l)oH`C0m`
zw5l2qKwiyt3L348l^diT2}-uMmw?)f@QO;NC<G*GglvV2AWNjZ_0~I>JbNCrda2mW
z)vd*W_xIr7f%n-NR;6;FxVQ$LO=_%JI}vxTnuND@*P>qZ=;`7rUN!&y@BSt>YC?5m
zD@=MH48cD51(wnaKzS-RABj;~d~V|d3~;Lok6_k>7<BdfP@mU`_Yc$oE)|?=gXkA8
zh$=jKOa>-Tn!*xlWu;{}TUm!by9*k>8`_{9qvABko;?8vPMt$%zXtmc=V9XbECeFQ
z!l_lEy7B~S+WTO0tB|C(B3a<UtkGixa3958(%jsv{>3kT(e;BL{9s8+N=oU71Ki;n
zaA?^*d>Qm=f^NJIJ@gRPu3gJOmy8bRLZf1U=bn3x3u5lN>n?Uo`ZxmJ;^JZk>;&B9
zi+{<ICAk0o`#-fn<3<Lp4p8QtK+Pw4DV}ENl&vKl+wh4hWocKfTE#ruo6S1+qqr8X
zR}N8$k2dJ0f9TL5oH}*NAEF-&fLZ}${Nu)rJ3MF3oVRApn)OahOiaV4y}x2(W1FvJ
zZXzZKC^>r;HjhRCJ{=q`H(UZBX>=x*0b96mi5Nep;#^%LDyr+SV#P}M1rR-X>J;MQ
z;!#`Q2pe&3#qgRlZyu&in~W1D@=#k@hG|nLBWv7P_ylmKVk834QBjd-ZEI#((YfOD
zo8GB~L2rVWipvCu?G*skY_V`rnukHIS4xD2>~b$;O$De7NCpPPy(R2HfHy!eL9GoH
zdj+`oj6o}bP<}|12U_JK8(n$?{eI@eav_>Z%b%zF1sNgGXDLHWeK>Ypf|yhtlavXd
z8ek$^YWffkbfqG*@C>i?H&Tc#EGWcj(T_7`&PGE`CH8LHjJ(`Jbab}BPFZ8C36p0m
zKuJXtPFFPIp$$v0eQ!B>on{o4RAFBBbWEKx9_Jf6Mc-)!5EUTR?S#YDkGlFgSgHNw
zv51YZ!D!IHFnt`_yUwGor9(2r@EN5Hb<l?NglK`YW+5&iMS$8Gab4t#NsA3CeE`~k
z7qLb^R<0V2dvBeOlqeITqYQZA-BN7bSB37r2xwxA0#sX})<?5xgwGqqnmbluX-+m`
zM`xg?Tbf@Ae5Vq9A0wVM!+EU_32?<=f99EIp82SMh-_*=H{#8kH}jGcT^J<v{QKYk
z9-~H$V(NkzxIPv@mjF5~4bgGPL9@%xe)hANI(4dYryAi1Uw)_Shb9v=Nt!)-HZRwG
z5|jey_dyv+0=A^cap}a7Xb6<GwOXyp1);>pHfUupKR=(YbDsc3@_kGb0uez0Y7Y^o
zZ|>Z=uSY~gv?)DyAxtKd?Mjl9Y5@iVDg%0LKF*j1Nc|utMvRr&m^yPF`g;5D+G}qj
zJ}DK8maV{ngL_e0l*bf+dmns^?OAh=A4O(XDke=BgSN&xsQhl6&OL!UAKHlS-X26n
zM6okgL}Ua?N=nev(+wXPGzd_cHF_MX&z7@V0c8<Ao&fs#dk`5J&s<(IjgYiuLn5vr
zlt{c*f&ygB;133P#meChty+m~se+Q6SCA{aNMXUtR0smXL_;8mO59tmS`VK}%HR@(
zKyNT|F`C!wVG&-!8)L?f!Gwtu(bC!;X6$eY9U(01ORGhkP*H^yp5X!*R;e^ZITpa*
zgO^`;9{E$IA@|e?^mcaf-wakG7EE4(IRfuE+(2SNs_1_eT08on5#Qkv6AX_x3dc?q
zWAdbNEazo0Mu>A|6O#hTW;ht|prh4>qSJoNpB{^jrgrQ*T#e$A8g%uGe(`F>ae82i
z&|}r2wMa=xMeX@|?A);*J$?OBrkjf6#5^)J#)n`2_;Jxc9_&0&0E4R!7E1~utOhs)
zNG_>r!>YBjV2w1Rt=S5qNRyjcM^6V&I-2ULVR!V1qn}Ux!`yc&$h;u{cQ`_}>b>5q
zByH!*U;Z-B)HiL~#6JcKBCh}OkALLM3jtj*OTQ_BF3k!_9f3ecxEv9=l0EXsBOg0^
z(~oPAQO28ZzB!ONr@@be#_2)emOw5|mZndi{;|t!Qb8saj*!$BO{BtuipL1l61Y`X
z2=IZvQREOmUe`HM*A5&w;Op(})rQ~0qN1Xj7c5xt;*upx{*;)QSgG{ZhYwmRKVMVF
z_tU7jB#a$5PK=FnME~2defutSw6(L|>%yhWak}U<gSUqsk*J7e6_o<mj>c%wrnb5Q
zhkbpBizbIKBO)vY<efZ*(UYbLz~jT&vT~%QreMj^rQ$wlW~Z^1mR3xeIu#{n3Sl%G
zVej{FHnpFe#>|my_v>;B$W5Hrpp=ni^8}S-L95m3p)&;GqPiB9T9OLmG+~hWwd80(
zpws7Z!|QUh`2)cQ0$l`d)eM^n=;}BlOQ6)@AY0i0QwyRZqcMKMII%BQ96xeY0L;!1
z?Lot?ZQL;f)B_248^!&F3f*MmiNHl5SQQ3zS@;1JXDd-%UBmPUlhGvlV+vN?vH~+_
z&c&F_v3T#jx6#wwjNRMbM|ou<dTauisvYR;=t60EHRe3H9@%qdFl9j#6^(Xxp8(Eo
zOw39^<=JZF7SxDy*on?A2fFPlxP5Bo*;<V%Oq)6u+4EPRxxN!S-rJ9^zHZhdh5)kB
z#sDJCIy86aKqY<_qaV9=mmwly30!UU*uDRtI5rg<as=QJ*NzpD(J@%Qa<#ZWoknwW
z2Tm20BEO&jvvcMnE>5B-Bqb#Ue)`j&jvemn__7?_rluz1EPd!@T;jP5Cr}_QSQ2EX
zWsLXUdykj;DH<Cad6|*+m5OD^ZRutxMxz-a@g51>%0*-p#I+?l!pxa7m67xY#@xAc
znZI3AQ^Q$w;_Fc{3I$ckQbvd#bnQ%-FoDkxJ>ufxZp!1Kn+jEjpE`AlsX&(s&ZnoR
zGpMD4Ma9~A@Q|epmAJWs?nT5SKXKwjK-`<u;rA}$)2>{(@^|95x``+WN^f00T3cJQ
zu4HaP#s)@<l??`_PoDv&0C)!u9YbAR0~dDb1^6RCNUKFFZdna=U^dQ{pT)idhgh8<
zK>*#wOP63%QzIJcn-Lc^N?<#$7+14UR91_b*$c2^*IrDTFbPYSF2dpC$HeCvF+XPk
z`uh6W%poHy6SY;9yz)lYv7}+!C%{%*Y$6*<kU;`xQ$yObH2V37$|wM*q+2UMqyU{X
zE(Sxkyz~c3GLbTaEG4GaNDgIMG49jYuNPNVd|WK1&6p{`doilcRdW`b3adts9*yXz
zC;|R!(b`rFo!)@dQKPV6;X)LP&(_z~v2CzF7#N@?P;r{u>5!Kf#NUD!Q5C{-a%7iF
z#btqjiVO2bXQktThaSMfC5xaXdIakT#|pqZ3r89o#J#K+eLjnTl77zO+WY&^YcV3P
zxDxl?c`r)Jel7r~WaL1Z@aPC5jAA=B(SOA?{ZfIOKLE8>h1qkaWB#nA(3;iQvSmM-
z>g&XQcv#6ILhZz)X|Z_pwrrM%`-gvf9qm0Ty!>VX^p<$|`s|{^^{~N$j_wv1)mqG%
zF@v+*QL)LW5ukhWq{-;+J1Neg566z3z$B`Bh)5XGYyGk+3Qs@%^mTF5=t3fLH!Z^t
zr`#1;|9<nE-()>Q0=l#mOBV_af@G5L?z``@^Ahn|KZ@)q@g0fxNJVinfTAF<f7@-h
z@xCeYUms2I(vrA-=yBhD_wlMgsM?xct$3m@2EOw0a(+-DAW>n6uS+x%YWGosMJgDh
zi5-F3%F4<Q6oJxBhbR{WY{!ouubgltKDI$)I<402*|Wzlev5L^7-ud>S2ian=OqHR
zsi~>ON^f1$eOY%UbCY-he82qlZ*eB>!2SbVSVTZbuQwt{$s@J2)L(J-ESg(eSj&}w
z==}Nfc%017%R_W*EJkHyqO!OPEu9YBbKe~ZsPrg4TZ23SXcx?#%XEa|iVC>JzTAH2
zov`)yqaZI=jB9SJUbPZ6V*5Iy0UouN$7P4j4vWdj4rYD<*hsrJfKU<GKz5XXuS5d~
zh9tjaJVHzLRBR<#2aC^W)%>g#52F}66XW7Ae^Cx5it#=+HXhmY7vPt_{2w$3FiE=f
zRJ2xHTq3p+K&$}qD_5_^7|K-F)uW@Q8!9Sr3;09C2}v3(z-T)t$&rN;fAYS4z~&dS
z5`)AIo;Yz5R;*ns_EW?A+0@X4*v>Z2dK*n<*ah(S`PKYA#0&22?Sn;3+KWpnuzu|-
zOqo6%B}L@|l#nHF5T^<&(9&oZ`>0_WiNU1Dq{)*pcV4#WGA)jt$VYi)DVtrWRbHMj
zOi0n-yPsc&goIJ3t~i5!lN&2?M&q5mt=M^}8PjG(B55?KESTZ(kxsD}hDaTz3V=%n
z9=*L?sH{1Q@sr2EBhF2!m<Z(N6=HUFDKcz9Oqo23k~JzZS$aU+XLpgt^oRr8VVWu8
zCqMbgh!t?q1^4x@e_hNf>)0frsHli93|fLFt}7L&5p97AYUr~g9rV2<n!k7N-ir$B
z=z=C~(L2QtSm8e2TtTY>^tk7qdw7CG#b=ZiCEzO;2FMOaJ9qA6a63*6XcH$+#H2}+
zxa~-;7SNzf1s{|tp$GBL2lG0o{UFK<tzJ-NuM$@mMCbUZ<Pen@JZS7ZapDAJY<(>)
zEp(3>C_JGeF#@$qmMnQrQ9$@`A;zl!C0i~xZY3rqqo|}DCyyS5)9&C!d*Zi}wyZl;
z+(kTHty&{MrvpX-WbVE99#&5J+h6`7#?odaBqw6!@|9>7uN%eh?8M0eB&H<8;dG#(
zr~uh>=cA;m65}U~M^?rt6c(IDu^4};7>c;AEiG*fG|!(q2ea5dt%6eK)@JKtt}lIt
z`LrPwg#lNxkf{PGGtgK`fR+*gKChpFtw!v-Mk8@`2~6q)c#MjQz<dGn7A{(V=$Ke&
zbb44U5n|sa;qlLX2LJifr^UVDbjX}RD}b8?ci+1Kc9#>IHg91n1ZAw78X8e{rg#9r
z2GybcQA?6ww0n|eu=I9#A)0g)s)6I7ZRY0}pjq@ox)|SyuAtW&1lX=ewAF&DntC*~
zcES=91B2cSufXw<)=192Q$g3(9s4kI%2YJgRw6z|2Y*By8e96{^s3l_j4;u{#ft?f
z7r^#N0qSd;;Bk223Ao977eTUA7N1<XWIE=|OvlS_R>7^eV&AdTu=RKa==Q)SKI`#$
zk(8K*XiGGjn)^{+-M}grC-Y8Y!nEl~%!p^2=Gd`gQC@Zq|NgH(L7&}*7hie>6Q)eZ
zU3YJwVqf*M&p!LQz=|`d{%gbmuIyy?VO_{>WMpJyu$?VY6=)fYIF)ok(}M;|deCw$
zWpoJu3};rC00?D}i5Es0zwl*Z%BIox-FoY-iqHMWAc*2Z4?178@<0<N0=wjTBxgJ5
znj$)YY|25LR$8_qz)J%L0nHCf%b|geCWW*zK@S4iM8_E_=$ev2t#W;RxS;cSy>f_3
z3{TJmlg82G$B+A+PNydP{v>`|r`D`l^Q$>?=DaD!Rpn$|N2H{roTJ*9%SA<H1$OV+
zEpBjrp46KKpmUR)7bsJw=Vf;WkE~b#I2{7$z4NXBxa|T+dKuicH8!){SYlclN($Rh
zc}@VcxI`EXM%e7Ftd2Bp@)Z32#lJx%z?9!B0Y9w(kRI`0!RbQWx_%wbovRk#sg+#6
z`~e2QE~}ZjxISlyks@|O!+-a)0)i?K%Gi25;<qi0-Sl^jM#Z3(Xaodoqa!SsIct^x
zdW#UBBKFN>fZ1f>A~gb&4oANj+s6q&9fQu!9_aK&2EVZaU?++(_q`oEFl*LqOr0ix
zWOFk*ySt$l_kH<(!NqI@VhOmi;zN*uszjNPCKwkLq%k;W$p=<hXm9VtyP{ve`R%8e
zo2%0qaq8GH?B1~*MFnTj)8~Xn+=J5N;?d!uVlx#yE(f~1{K(5M5)+IiNJxx_tG8Xe
z??ZiaA5t<>upoPmz|RJ8e=9+CO&x>OV9>|P2x+lFtXnk=P3O9Cpr94|57%PS*c8};
zR%p%ffTb7JB}M4zcfoA+!J-dh;`j+jOC2L76B?X6brP*@EjWDi6jrZZgUG08abHb?
z%jxBFVUDnh{q99wa|=>Nj~&r#eMo>C85!AfJuYMvq$^3B#~Y<DNm*i2B)Iq9dwHOw
z2LTld%6z^0>Z@!VK}AFa3aEnq!z?$;ASX9BmzRra*&;j$^ekMskY&zpR{o|Emk*-V
zP}ZFulu;r&fJ|Em&!SSHS~%dP!HP10GT0^XOB9Fj>x>4!_V#wp9?H)IvPjk|T&MQZ
zph7sJ9S~iD3gVKJla&+o2@aAlBlQ>>r!qN%qx!@hBmK5$96fgIm|y(H<V>w5lxg&n
zw3h(3zaBew>=EUPxN#8>K*T@=S6VF_9nhsmj$~9wMTJ~U0|+G=B_QV)psG{KnsSmy
zKs5n0Po6x66>DxmeO*0zd%EFr`1tf{jRtlqql{-j+)v30I6(l$Iob0hdC{}wVv=8j
zS~1p67GquU>3m-9w%eSXktNx%<kWOHX{D5w`UR-;i|qsiAg4kvw?}dxlZ+H3ZY>v(
zslhI3MgfkePoIh<OO_%tD^mblv)H}>wPL??;+Tm7L5R}l5dc!<L(bf696WMd95?le
z9u6^1H@CEMfhrZ;z5C84#Kgy8)#}x#75jbk&|#(}s6&}rdCg4{5(|Oa;DyA-1rrFV
z&`cdNpCB;2Z}%Q7TChj}QZ3$j`)!;#eVWZBykcKeIs<yUyO0nQ1Cv1qyGv4e@VbKn
z`-t&l>n=QS*9P=Yt3hGGF_@!LkvM8J8fqI*R8%6ci;FdQ$;#MjwBy!WCgRR@3y>Hk
zz;$gOYCHCzrB{nhyUxQJosI;(7kaA&4gtXXY(9+5OvCzhYcXl!SoHL|#Cz>nvUD!C
z?bwUnJ_q*h-iPF*6m*Np(V_iEvG@J`XlQH_=S$ChK6d<M8E*zeU;dDA=M4e4!x1F&
zMS6QTIw<Q*stS~ele4R|yi3_tD*U3X96bn#64<3I*p)O<o5k#mGI_K;0y~3g`%?Cg
zY=x<)N2yl-<OFfc2vE|4f+jR{Ey#dZ=I(}PVd+6D2ca7^XIN>nMcG{fE`!kwE)BXK
z2^<semw0UiZk1xO;hz+L)N+WIhJ1}sP>lgSXiSrN;Pm`)SXmnqJc)6bCWQ3+5aY04
zjHMT8*V5|Y!i5X}vSP)G-^azpomZ~X;SHzLX}yxU34tt~0F5lY#oDhL0Sq~z%K$1E
za-QXECAoY-6*5Io4~%(~DQ#_OMt657CQqJ%{1b<9rnrJZ*ou{FFk{vnyg^c9aj}@6
zlZ~m<W}>RP8Z8~|m^EiMmaklix8HsT%a<%fRb>VAnxFu<4jwxxGwiV0cr~`Krx*T!
zPk=gi$X3_INhsO}0;;r<%Ee<EN)iyoY%CTnUW9Su$HHK>!fLT1!WzM91!~T;2B8)0
z4C1qTjTW~4Ua^1k(Av?1s&nThJzakQ+uqxTq|_7!^$v%VwR!2jzj(<K<e$oe+wSCy
zbU=2UkY@xTs=}Zq5aIt00b`<o{QT+vg3C>EX<k;3Ao>E;*ohMWkJE?F&JM&Ur6FLq
zi9bnPU$@hZf`UR!9G!vt*RDZbZ52)x)gr&7TAY(U0seGcVCVC>#bm~d|M{0kkul1E
z9oy=~_|pxG*^M}TBpN*8ephoI^B0XnVoHj5-wJo&7#GrYwDoYN+bcfP-P4BH1T*fM
zb{l#HaLzrEha<;M2r#Qdfw<o4YMVf=5julK^syRa#!bYcrOV{sd~n^mbw9sh8C)^I
zW{{*3Rr_B~5c*~gx~Sz!c;d&BYZ%cN2&~H4H!9Yl2Z0#6c~F54aYZPrM$5#sL`;ux
z6@*JN-JA`k2W455_~Zu-s>JQ42L(wNQ3jUO8Dwe!y%&B%m#?{Si`+}ERRUXd4N>-&
z9yDR1!C8q<S3Lai!(3B9+-rHMlddP3ZbdghqFha$JeffXal&u*i4SGdXfjB&pWNKs
zfcPD#!?U#%Vgh$)*|KGSBvS^hR_j)-gpmnxZ%?_Bxe4bP3FN7?Y-h`EU!1j7k$kK)
zK_~Dgz@3T^951`8B!Elw1@RxL%EG6@sY54l&xQ@?xA!6@HVQMR&g3M)u3dW=WG-2>
z2rca$40h}5Dq%8c;OI=nl<b9UGH|ZE0#m2YLSf!9Xa!33xZKbLwdm>U6rfH6zmF6a
zT%2^GLMzHROB`VpXF#<A5gPPbWTmHI#fs&~95WWy=va0}Gg~dp@6|9V*2^}-I)MeW
z8iT+G9<k4E@o*tBDiS$4^U>Ve0k<c>++#A7pk&shDO1tf)(*W+BS5kdXG_lt(CKCg
zvjAkbvP(F&vV>SzV&nqCl|CRfk+gBUyZZ++(Se|JPoa!7(=xPrbobd17w>}KZ4+H?
zfXNaCd%uH==eE4N9q(`5j)s==useeS7?b%0xtn>AoL~~iL^{V>boTV4r>`9iy;elU
zC8D4#7v&AzVnU)~``x(s1WcGR3r14}&J<OmbJs4ki|=@U_d!G@rXn+I6w))3#bsl{
zk|k|8onMGf0nXpqzLRMeYB6CjMnuADjzE{dSFO!W;<!eZMz6ihEH8>=lqeJWVS_SO
zG*FZNC@uMZlo1mX!wLrUpn@R+x&&-xO;q}E$TCq^3d+WjUMc}+%C3D9mkyP<`k-uD
zc!rmP)H7r*Ej_3Zl5X-uSs@BTLP7#R%MW^AQP#NeL7ATGl|vlvpiKRDzVjU(lL!<N
z4T{tRWJMOb8Onu^q|_o8J`&g^c{{2}xEW*;DM>*4U0PZi6vq)1*T1||13O0<T2ez0
zkH04;CzmT%<joOeEFkH?O1i9E7{#S#A+-V-n6Wy5YM@|>wP1rfG1fWRj+g%H?&`vu
zZ@wYG&nU#j#$xZ@_gUlh?)&aTs<@YK-MocY#K=`^(SjLRzAOh8b0jux-Yo!b4qh!T
z#q5kxFq$m_f~o|Vl}s5(>Z`rAHN>;^^6x^H-I5ppoZ=K9J{1cW<zUX7*{}+LMN|Yb
ztspRK(i<2|>I66?Y62y?oC4VP^z<`dRHxVT@2XEsFwNE&)Hk)@_=!BoUvlPjp%}lD
zux;xW2Ap0oA?@nuVw#40kxPB2`Cx{2u&iz9_Z{whrjb&%7kx$*GK(PE8p(foeFX5G
z@H+d%duFJ;Y6jRYj~ku+y{K$!q&<OICqRABi%AnA@!%b^F@N?r{Lk-qVfT?Hyz=Hr
zEY6vUZihomZYVu(hRx-J!{)~N<;$^baSq0emy&-ICXB(^$_zBNw%}x55#}yh3Tsq6
zoNf=!Rup2(=54SE@Easrh`|W6(Zu^QZQ4w%UA-F5{NeZL=@$ESwn82&)XzWveC`uZ
zJn^u&A6AVxz#WdDSsGa=k}TFo4RFJQmVN0#{29u+5nX|#qAnH44;zH}rbC59^iX)U
zN?a-E8lgwHV-O9>N=EkP3i{1ouN>k?1>J1r6(|Y<;skbSd6}}ia$(%1g^$!u=6};_
z6ivcMn$kcwWLl-DsHk8Hm)JjlPfw40v8xcKW^c7xJ7&+G{Wbwxve6~yG383UaS<6A
z*>NRv6PDZZli625nk)rEmbNOeAp<EP1pEl4BIVp<NcT15K})Iyq-RS&lPp=g`+CHL
z=M2<-74vziSnb6ZUqnww3nC+Qc>J>)F=f(d&Zc&E^}(vLqv?D(ri(H3+}R>boHP|B
zg$1k!OIck04qjOeNX7|a7aQ9<a8a2WciwfoXgdxO(ebcYBP8m9PAdSZ0P!j{BBP=>
z^V~1+N_%?`Tw>b>y%8zNX<S_9aP>jm+ybMe4Y%KME6T++-q-73@ZTUNnT@q|@Ht)R
z=;>j4Loj455e#KvRZxB4w{od^!iCqtL9*%6F@<M&>3cY%OUEGkgE+Lkef_-eiE%Md
zi+%^0ONhya!ybU!qY>jm5Ybi#zWDHB%$q%y<+@0<V#&g(I9}L_>P8Rz$7+x|dA#VW
zI2gNn1;F*f=kX#YItGa`5ol{^METiLn91pE^-8??_GWbUI&t8@L3jgd>^pD-x%ma+
z`ml+<7ZW70Z?os;U_nj}a!=(l*gs!egSqqP<NaOlqwajIJcg-iYiqN~f8mB?aFddf
z&i?eLKfS4d>G01|FKD9D51wuy1a?V{feLu!<zmI<NQvPH1>7oeJt3=nkaanMT3J4h
zfNgl;BV~RGXwoBWJm*P0fnK6F5Sah4pqI8!V`TW_+_`f>F@X!elWQ*7_mUYiW^56U
ztzsXJD~1doU5NAEePweKf@y(}6ITFc6BS>P0fdj8!1P)z+yO5`F9MeuR#m`&ijYA7
zSdxZfY6JYCqAKy4h@%4ak>gonLIUf0lQY<;v;-u^#=zCrfy(kTsIRGm-e*HoO((|Y
z+>Vlb2a?6Luh#0g$V;X2%4m_D$XF(ffUR1}Y|=fOGQ1=!cDB3>Idf+*&44C<L4Oct
zy#Yq?+Gr&0R*A#f*KcEO*|gMAyuwD?>gaAqZEdxf2)8q!v|3GAvUnl3@7N;%znTl)
z_Uzil_Q5i>KotzBAuw$tAZZ2%f){08FPFg`G^-0-A}7Wl;8njsK+hcH&R#pb&VT@#
zK^Vlo`aR<OiJzIvZWDmsB*45IlgB6E_Vu&y-lh`>nr4YHq!KmfPK#Z&!0mUS-{C^~
zs1%IJoQSlHvDkO;B)kIT?%96`v*yl3V&-_H6O~SkAzhs|RM#}JVbYNkCvo&tK5Pyj
z)H)5U(NQpHOz3lp@0>CfMFLD`&zq08-+TjQV$6E%(T#{pl%(E9GKK`W<Oxg{;q?S9
zz5eJ&Kl<3{OUgG8C6rL&(-Fj{UdlG1A1}LXq9qUqmmU<v(Iq;A0GeDgK=g%h$wImC
zkrWH$AiZP)x-#IUXPVg4M69>BmnjkQgNokhS!_2TzDqqwk>o{p=;-L^#t9Q99H0#C
z)TvW<h<izma<zS&f@HL437j~tfXSeR$K!z2VuIc7fZ1YYVC(ftW(AU4SSXVlDxjha
zDM^NDLuLw+x&mc4)o=>%OV=OKX<{Ox5NR=D$F}#780CiF(FQH!LM`Gg8Z=ZEVCu}7
zC@VgLNmHky;N(dz#3bw60NL(JRa^`}jRupLfVt4!+XD|P3ItJ*n~(KtRzamv!6)`R
zE+$_5-mL<Z2GQQt4Vz6;LCVO?LTp?-JDNEhHgtA%qPMRHF1JSjc9VDjogJ-Mx_AMO
zA3KGfUOV?wKvs<)YJp11bcd5{CGA}GpoPWZRD{c%iVJEL1KD3Nc&5y=Mx%vB0DqED
zBRk#ReitIudidNyR;$oze3C|RP>(akO*nM43Vohv#H44!;!~mV#A)=B{;k`Fr1*49
zoiYszbCx47KOd8(Oh#euX|(rxaQx_Ttd2^+*r_w&^Lqurt>i4cN4)kpNy#Drjp(F^
z$S8dFv!7u}wS$L`pzKTuI@{ZkmY%^yjU8>RIC1g>maSNc`s#ChTw?t3Kl98p!_M^_
z65#rLKK=E&kkKHl6kaKzgc3Jv(D=4-<Hk=yR*uzR=pkoWso0USymF!JrE-P@V(CFy
z;A;r=V95{xjLXDWpG$>e;&D&`v^Q^bbabS>^wLXw-Cr(=WwDxI*6YQ@rdxnql>}5(
z658?z&?hgmOXdZVC2jaTM=L-V(XxC#FRK|44^<W7>vnZ^G036G<y&vO28&sZ^f)b?
z8V{m0#9tNd1bB@Uz_P8g0jaa6AaJITu^xfz-p&rrz`9)y2{eZ|=d?uc7W?M*x)AV5
zGF^@JP1w6<4{p6{9ZY5;Yu$DU0PJ-8SREop^g&W$67yMmdi&7V)5S$=lzFD*|M<iN
zxSbyKbak-H+N{}gaqF$?@y1)5ng7bb5(v=~LI5}9^fnm1Ae@%KMPp$T(cmS;XP4mH
zfwr{N&!E{KWZpCPwMR@Q)H-zc^uroq5&w3uDTUq;D<&enOeyJi8S%o)hY*)I8l!?|
zVfO39M8O~cY%>x?o6kJ<0OAr-QC3=l!lGQvm^lsoy*AW0wc~VQ31($4fZbP$f}#Q(
z*s~8!4XsQ;QR$3`7L$Xq6UMXEa$mm(hmO6Eb?et*&$gXtZE6<Z?_-mVNNWVno~=Mq
za>|IWY7U89#cY4#NV<?Ip@b4jC^0fYOR-dNMi2RBN*P$9G7zOeekL8}@Eh!9k*!+o
zr_3x_<C5D@dU|>hJyUU*V!rV42{HLG6Rl-1sY^MiI^W*!gvLsiu0eS1E*OkD0pbGi
z1hojb0t{G4p+F_x^Ro4=7JkV@jA0o`P)Q(HEtRK*)D>)we&)CyKXeFR`0|rT&B#Pe
zRRz=nkQ&7!F2w>*pkI8K_#Wtxo*IkR`f|+9p2yB=q;#}v+j}sZ^rSi^KA{b%ji_KU
znHlhrS`B?SaczSF<yKW!qNjfeEIobjdFo(_jAc+8n~=!+>9F-Oztrmqu=0VyVCK0T
zE!+3?cjM6eyK&<1K}5$Vz+|;x$;xHed*}$dJG#WadL)T7M*6bG?FA|UgWk|&;9|7|
ziQW+$0JoA8n`H4D#>Q1&;Ok0-b3sT3Y2rP#^ja(a3mS|pU*`4rnQmb=Qh$@Vf>Qu}
z0p>NNFyTXEvmZ%mR*W7sT5LlNLsT4m?kaToY}mDPFUC!2K|<D80YH<mZ24qlWo6>`
z|Mwgk+U$7k?QO7$Nkna3oiwp9=%Dhcp%dqxb}d_g|C9Oo(3y;As%ylFqsK8nCkKrU
z&4`GK!d)9Sps}VFTeoZ#eYy|Xb7t`&5(l@bsVQ5GEu}i0&N<=$cQ}FuPz59_p@b4Q
zYjkmi_s3ff@oIu@j+CvV2PweFK^5p!dmsZ|deCPDKyEE8EKIul?z{hmXa=Hh>SAJI
z>J=dS>4;#E3SuScECRL!--xQ<6hM-S#|T`JYJk;ZWUg+Xo#+BS227Nt4TNlSY4w+R
zxB-dEK){*Q3J8ex_4FY3)G0PwpkmMFmTJW4P3Vo%LvOIc9F>Ie6K5eNbu`}FcM57_
z1iNC9%E9RI<IzxC&9n!f*T)*RF)^`BpP-cr!k8Hu>6{^KZEZwXuM-_@-2x2jFn&S;
z#*drGv?Qm~h0eAP^!N3Wye%~1SjjxW?H0%BwBgj@z1Y8dhu9wz*57p}7rHr}epFRd
zAs{|OnQZy@75*HQUk9c9>ji}e)kV(;2e%(6I1BxDL-K5)e{uhYmu1SCV2xHI_S3+o
z8y*32Q<7ttN?_~j;letfI5$q4n2Klu;=E}vDl-i+3F%O2^(Z@AEzU<LP8Ako{EV4M
zNJ>VA*#wK2FpL>9mif|Ez5O^-Rzb5L@m+d$ob%Eohj`H{nk3knk2`((40yaAc8II2
zsKDGgbHud*bhNghytEx>OG-HN9o`3|qVV+7Pv_n+t6r1I)O#ac$dph*2_<fHP^Ra4
z<q$v4LCdnT?s9l^baa#o@Ox(d{P}-Z=mwvx5CEd`O6Dd6LX83xd3|0OO-A(F91Lv9
zyum=#JiTR1UR~F<ed6x!?(Xhh+}+*X?ZjP*Q{16IaVt_>iqql_MOxe)zI{FSo9_<^
z$qpgeYp=EDm}4B%rZuPm12l56i(Ii<7qhv$`&uRjZG&)t(O<rdd7R<oaTh@4X^D`3
zSRg!d9Y6dLy_|f%#jB@m@Q2v|OmLHxFiW&^37aaw2o-o=WVZPqpv-)J5a#&gEMk?q
zUt3(miSko&c?6M_$=AuV;qQjaC7tESy&}PYCO-Jb-I7Dl6FbybN|Wleoi$5>>$rXn
z-b``TunN>|i+J5=`=HY#LUhQIpFq&!Id^nxv3w3iFQ6HH-OM=8*StGI!-!zsuL;}B
zX@>&m9dYHt2GfDrpZS|9oO!4+N+&<t4&ru#U}oPZh8_h1Lhx^t3NhMM>I;T>Tl}^=
zl#-wr6QNh@13dVoe*uQ;^7ze{BKRM4_4E}zP=cmaBsBSMzZ~OWWv)HrPK{Hfl1Zz-
zGn}sU5#ea_SP%v9_RGsFj=Vkz0A7v$+(E8Vv@_(vztx{${0b;%Y_&%Ol=9g>&$9f|
zg5KHewanwk7uy?=9==%Ur=g{#s&5pe?yn$t`R{z?B*2lFYXNp*;L{{aK`&mq`mL$D
zS#mpE#RX5DcA{&WjUo|KRD+-uU#1Ob-h?lpc#OA`<<}S-%&SK^<yI36iT=r;%VRN=
z-O7pF(<)bpvF7jfi%%X3T?(14z{qH{AcUkyqrs~i+%&v{QlpRp%b$GE;8S(OS8T97
zZ1ZTMgsm?cY0x7Eu}~0v)Kiz+3Q5Vud}Ad`1^>%PI|BB%?mM5;troJoBouj-E+~^9
zNX{rcm#Os)qcO*^_~NG>WA<_~G6eT7fpD87EIHhsh&D%4Q3l}cvN2W5?H4#TQveSG
z5!{x{081e`AOph5K3+8W(v)dB8D+b><ICPyi)eq2X*Y{Krh@9qz%b$WbP+1&Ekk34
zBihWgl;#&_GL1V_?`-TeQmbu0BHf3!*{f11eH%9+p2&mAScKNLXuErLZ*jHflrLt=
zlH3jT<S#Qm{sjyP5tKqE1e*sMA*_cGjKGN73(T%Jf$3GDqvZrzCLN^f9T(s+^CM4{
zuQ+4Lqyx`}OZ%DGrZO51nBUjeN2KLF{0&3b>-C!5FiZjuc>dsEqfl2;QBp$wv65wt
z=7Zir{Y8$zA<tMA1-v_VP1p(B;DrP9Of^d39+QS$;Cm}~Se##_5>F@$)0QsR2b=JP
zoABkMR;@%6=|DI*`_N5g$+utLy--U<n8`CH2y{@S+B6wJuQbO!@Z{6bI3P1nq@L(0
zxKjZBkLZk6b+=oe;<DL@o<WaRuiG+ZFgN7aw>MOX@<8|NVfPK6BV)gJ)mf?!E!F@b
zq1}goRh690=FXi@lSbNt?Hig;IUGzx9UDGK1}BX3%>7w9pn8+4n6UZ*e54ene!=dS
ztx&YKwu2mDYsB-AOQt!ZDSod<cvLb`8n9~;zm3@X?N^?FM=4=F?VX5G<S;Y0VgqL4
z@lRMW{UAG(P!aqn^Btqu5G6&`v9F7@pEL3kH+qaRGK*wp!eRJLwWrfj5a_?=sv`Hs
zAN-zK?r747QD%7^W}J7(WmHpN1XGP6HXartLkFWKeo~CocOCwT!*uz4;#yYHg!A#R
z{t=OWOluLCb&NkeJTk;O^Frdgopj^vog-|IxfQU_veEwTV>MflU<rqM>0d!o(@;MY
zw?DSyv7)BFMblrOa{W_YDRJog-3f;vRYJo3H4@?o4;4otB^6Z!5MO!Rbu&GYg52oq
z>-!@TcyBiSg=e_}N>R|a*%04-!|F^%e>9pNy*Uy8YS$`3bHS+`DI)d~=(tO@SLs7+
zma{sm=9_+>i*Zmj;-ajK>7ZML|H?@ERivwABG|p{%(|*vaXp=0@NL{aj-7_)0P5^u
zfUZYm;_Eoy-oRSS!`)(gRdB}B{O*|oYb@u5SE5&4c01h!MYCXE*8T4X&RKOA)uWsl
z9+(0l!I<5%zr??~`dUTY+wJ`QtM9#(=i6|$3i)+C7B9`t>~m|Srp$)cHRl$V)y^2K
zDpD`+Zw2%NKDm&E)c-pA^VO$I#95V>2*Fis#g(R~_tg-=^+Ww*Df*^^vg1eA_Rq`^
z$Lx0<Y`m@nseHq?`7*f=_xVy8He_EN8NiG@jQ{yR5vNF8Iv@grk*CY^X`U&B&8i<A
z$NV6it8AY7T{c$&u3BfBETb-9kx?7o$(S+@2hvSizxYf*hN?gU?bGRZV-?tMH=ej<
zZB3{JEZ&f{|I|`VL1i?AO;-qwfx|~Z5)g$B^P7utrvjdhK+mdDqZ&G>v|+K@TR53R
zUQ6*dwr?vWBRg}qz1vl44;TU$;D)xBuHoNR@EiC0TJ6>QISD-*+i+x@Wz&^s5#BaI
z+_fh#jm)wLlxFQFU<@hrPaZeCVp5(bY>_%VO>+&dxots=wFeJANSsgtwkO-h6;9Jo
zEurabN$4VSdMO2P?XWQ?wFjIDa&vQ=JfcQteNhvG(|a4hYlQD7ik#gKR}qGbvmmEs
z%J{q46G%ooRfN<#kr)}t?G-nnB&A68JR*|o<Zmw&J#MErG8~C|+y{3dr@yM7UtcF3
z-pM!bUzjce2Ltn@*J(zP%)zE7_+e!pRN0vNGR8(L2~m{dKV%i8MK12F5yY7`!mor4
z8#*2zR4y5q3&Cm*MEAxgCc0R`Ot1<)H#0)7&+~F*Bi9F$Pj{go51}_G{?E66A4mE6
z1}@H4nxNo@mB4$;Ki+w^Q~w@51I|#7@p~)vr?-pH52&+HphCP-4yeBW@v?dGNK3L6
zvfUTllT@;{9eB~J$7VymykO$<>3i#&=d8#Wp9`UxU2#`yukd4JM^$?(@Yw%b$mPMk
zts*2?Bt#Hl18eC}C<^Gtih=(E1>yd;ax2O6{$vAO@X~weFR+du&nFH0fEN(>kR0Q`
z)nDEN<1ohXemss)tf$u>7XgY?!kVVhH<73*TO?Q2qO#eT4zwRj|Cw2RfX}5y?D#wI
z|Cs&Ayu7~#mh+q3n<3H6cKpV>K?sxXb3Mwvq559waO5sP^?7fw|5fR%2|BN0v%A`~
z;N?=ea|r5DI-~MuR|P-i4|lezo9BKS@`BwvNc#%mE?HngrY|JlY<Bwh;3%?k!pz1z
zv_L099wH-x0xS<>t9@{gBVtQBs+v#PHyQoq8CN<FMP5Nk#>j!vVr00prY7RfGbLgB
zJQ|L4ux6ib7rQv6IV&II4#o_9AKyBaA?4Io0S*P2=@OR@vkJfiSpRX27PoaNgV@jj
zA%PL>Oxpdn`LPo*K2DtSONNF&z)9@WC#Jc@O{fABxPpnnAj7p~aX$`xR_yfoP(04&
zM>C4tPnDdJ!$Vs6u9=k(P(`1$Fmq-wkQI{EVRdh9C0s}k5tx0(3Vad31TlLHm|6w3
zk`6YsU-AfxuVL}!xg;WqXS`tTptSJml}{1OG!ApE=EEWTv$U7Zx8KWh@(PlAUMZc{
z+mVzZcQDy2^<xZN`=jB=Y;KaCzY9VrsqUW#@)c_UeHu9$;K-L7c{7LcxKRQB8su(*
zUmS#iEGfKt@kb@^!<?9yx3hPVJ&!X=BomRn{Xt?WTZNdq#Ym_0+qLiM@B~00e>}vJ
z3IPR6rv<S0Kw13R)&BW$iT1&ss+|_$A`hT>4wpGyvzryIa5=OBe<GqRnZO=MwN(-I
z<^vBfM;*oH?gE=1lUMzjbxVTcdgxz8Q^IjZ;IWz3sE#V+e+U0tt7x-E|NZ(kh&ZC{
z<J4A6D0QHB?S6Mg!6Ps?Pex*l6|Z~z?5`kx-CKl(_;<}IhZqMovQWPlH;#{iHPr$^
z@12(2L+WftGSc0%p*xy`hrx!s?u))WUAe&s(2m&|+)I6AM|LRF?wQ!X?KQV|oj>=>
z*M?mSuFj3y@tB{22qhCOdv!VacFoma4@qW1a;AXr%Oyhp?+Y(+CUhj0WjG4^?KFf)
zm4+z5%QxZ>J$q<75(PomfF4cNSUsOM5mC@mD?vaXZ=15rM0-ltc$no~Ef7k2HhuIN
z6Dy`EmmyYFSx!rmaVi?$X|p+w0ZD5`I&bOkZCVX<z1dT~lU*@}Szd9OY}uZZqbnay
z5{|`Eof9+0*xS)jNJ_+uF9nSNX~(udQ*#Smabq=N=;MCT$PIztt62r?-s*F3ntnLr
zaaXE$W=mr;g6nui;xUF-54X<5KMZq$b#!vl$auHU0fR8;!o^eQw<Xo!Q&;0yTre<g
z&7if7cYo{ULe3!oHkp_|HeC)a>MYmkT^wxa6myr*hU}v7HAfE_I=aJYYX-*Z?5rR^
zc==yq&`eEg5`V}1=Xt-oOx=-SF+vjKf*k&eaNQw`va;cFGw${1^ufUyl5ULa$4<L=
z=@Dx!ay;|J>mj^L4w|rdJVnM@_r7+6plp4UUaf<J0};2EvyP83l!+aU1LiB+hUMu*
z7n2BU@PYO2WpUoW3JsCwhG(}9GG<Gu$%|}{t8X1|YBqS+8h_o|$?6&!Iz-;o;2hc5
zc+hMEAse&TVlY7@b#G?He*)HjfyGve#W2sTCn_(=K>=;c&v)%V2tpmDjBBZ`42c|!
zG%R*r1&e~NC*WeZ@=AxNG4_0a`2a`jUbZ0d8@qv59giX!WX3JLI9Lp#nA+Bc!=2ZW
zCISY+gc}l{5LwnQh_&2t-CVm%{hV|JoMeXv&N#68gn{7;(})O<o+TiN6sIt8%FY{n
z$owb%f>bPoc&TnmLe3QgAw{fZ5$+HlFMYq^UoEK1z%qhVTvvkZk{a?$kRhFDFcEr9
zi=r)BDhAbZ_2*)2Yfe+ZnF9v|FO?MdDC-ba_~CUM2r*90SczWwr>{a5=*+HXV}pW_
z@q0_YhANO#k`oBdH3yA<)2q$oj))VKvBcU8Tp16;h8^txmanD03prl#LhbkzZ5@1I
z%UOHrzgb=LZLsdxX_$_B(29HS&sBPkkZKflA6^ZsWX?4&ltY}0c#xg9ymhuyCc>kS
z&ppSGWPM4v0E45FEOL;rg=xNzP^qOwu0f;4qC-9g*k?2`*Y7GympycVnOM*bL|PR?
za;{b4)T%TKAK5%Xn28q0p)Ri&E1p6XdtQjj0WoiRe;NgplrS-q0;S8(sUY2rIwy~4
zDFi_KmW)$Xjh#qi6B2qssh|@rkO0fOa`zvi7i(jg?Z}eL*DjL}T3~}>AM2A-=Oc<L
zYVBAI*u=HVI|#Uxo#&9;e(k1!hc!_+=PW@oxP5&fI#C2{0~kBwRx1YD#3FDrFbF1J
z01KwdW8{cgUP)<i7YnZOZD*2QhVZIC0u4xUQkuM;Bp}zs-Y5{5)l@5cptTs(v!_ez
zI0`{IEZow3A9%UAko}|qX><;%`;6fCa%Rl0sYUy~gf^HZ(cVi#7@dMb6`LjVCf>iq
zEY7A$D!HB>X;*>FJ0QD;204_GOY6pT;~<bwqZ2HyysNQk1liFH<H|3ec^XQiraa=c
zKbEv#=WMLp2D-(VqT1@PT?Uzk7woY@EN~u#Nn&ZV70=q=8Vu76Cm@U<=hs(@drDFL
z4g*8Sj!Xy?6r~(6>Ff>1VdWECT>O=B)Wph976mW>#yv-oBjpk5N;=QZCg-){@-5kD
zia1uO&b<FHu&kr_j)zbEk<bZnXzrzA@?jKH1OMgZUtWIz%_$P5=Wn~wAfx}@%zv+E
zFC9ljL?q6z!)1iTcY~um0RD=fgw<nUVE_e<8?xuqKM-|x@nIe9XV&^9_)a5UJ($ZR
zq~BEY+jO8s7+YaqaXIRRxgXHuIC=?wg{;|df)QcUp#L(^OG~)IFH>A~_0MxdDQ44a
zhK;T-xZK>o%eMal#f@VsFCzgA42|DOQpfz}Dh*C62PgwX9cB)xmj%xRa8GeUpMDjg
zdv#YBu!mu$kP0Stc{Z;mTKuZq1ayUn<)g5a{H1Dn<ys=po>t?hojlIZ!wfX%je=HY
z6sw5}`s$6-QP8Xr4mJI(Mg+TqH{>?x*~h!E5zSo}BNPhX;#@Ia0^B}AfY>l<&&~Zh
zMGY_K*5&oK_CKUm(^beE&e?_S-@8x7(j#M>4SoY@*0ER(=>SOQ<E_`u(FymBa0eJ5
zWIaCqbFin&(~OrurpVXA_COyxSOvCPF?$*-G!N)AO1wVJHVoihDqg!%I3SW_4cJMD
zTZ?-*z-n+I>oLsKE}w+|Iuj3)B(~VE&=!Xryt=wt918v~%tk~+R0VKM{!h#(>H{+L
z?eBYdKaQUV&_Wu42uX$3-_NQlD`)rBz!t-i5=;+P)K_A=u?t4_iw!tv?Am?sE8+du
zDOl*_=DkIlxYSBDx~%+nAnZ5>X7OCw%kP$*pvMW_%r~v@8|@zt+8Saz9>LSqw!G|Z
zC{cv!v$Z~y4tVf)w*$s<TH2N@2YY*h_tz;?z(z7!tU{&e9Crp-<^~SjC^-cY9bNPj
z%IK0kKd%GozT5LK!VG@kTgdI*%4O}x6Uxc<+8L&4b|y*d*VN~5XcO%aoXKJZM$xqE
zh?LGUSuESaH>EbU7!YguY5mGfnzf?)w`bxnC;$8d7mlbI!;SoW=Bf8E`M3yzAhX9K
z=Y6AoW5_c-&V>al>6^vX7w3OR`2^#pW{O-cML7IhM|qSuA63V40+EqCONsyA2~mzm
zlh0<o-<@mdzOyE}+g5KN9S}LvBPglrPB_aQiIX(az$OiOgqY_8tK&uVz9g4@uY~1P
z%#{$u>&_j9o``M!D*MN3RzgmZt9uY*cJ;z{Xv;M{S>0*-z+(hIX;icsn#>(s`=9<_
z0_aS`C~^mG{1(G4vVW6QO&f)BM?m#o5W(XmiSg3jZv4V^I;jM^Qgs~?{dzBO*aQE(
z_vel|`$@=?>&W7+FxU-I>@GY?T7FHeYBgtgcN@_&GozcWu@KNgmmi!ZxBK*5Un?pZ
z=WwtPbw8X*)q|2RKVd^S%OfT_1=fHa_I}qiewjwjFuv%G3B34$Mym+ToPb+ge#|Yr
z7YL7tW!w2<I~gPtF7fr1?ouvDok96$klAScFbe8p7ke_I*1%U}(X7?$bfp{vNVkkA
zlTJ4Z##%=IK)?n+u-?!+u&yzwcpu3Hg_nT|3)KZxj1A9n2M70?0N<yU<_lcd+Cmyv
z$!s*|LCHlY=<~szi2REJxruB4Ym@-|R~~v6rU=>kk<KfuM#p8=I)gSuhx%x3HVZ7w
zxvdTEo%};AtS{#?sMQ2!FS{OVGNy)~^V6u4RU_OjX-mF+gGj)gk#nvGb%x}|)$U#R
z@NYuu(Z#>pgH?#LO_lOBG=9x5Z2~l(hXFzi7S(DVAYY*R-6co6L8Z!5V_;NGa_;{=
zq)$PdQnib)b`xsCff-wmRx%nI3r|eBd2<ed<uYRgytS)?xDEE|4*1&j@>&m)XTA7~
zg5j{-wQ1_Ezo<TeG+QvpGdZfJQ3_;dC;y(h$wrwndRHG$j1ks17do*I+giKPihG&L
z@g<XPOs<NUcw`67;|p8Q=EaOKWm#T?y;Zx~^*{4CV&GvhfxPILb!tJ~-R$0L+*4op
zvaLtP%_ytWIHMeREmLFbp~v;!$jSAmKPec+h40)wuIT8&i0KBX>*%`1MamK@T4+En
zZHEw@`tbdPHtTsQ44j`^A@B1PR3R1#dtSTIu<$NURbrVX9{i0jDz9$lnJ5lVJoyi~
zu7W5-1u<eR)n5A2VvZSuHhh8ZSk*xTJU2w2Ou-=l^UKDjtgi;6C@=_O%l}T9o0r=h
zIDGu>7MD{$=SDT{k1DddpVbHT9e37j`xQYf2`~Ly1oT_U(c>$~x%OC5$Wv4y+C(y_
zgbDCWA*n*L5>2i%G?WR4fB=Beh$-cwsTMYbt))Ta%|;7>NKK+W8Bey9dZPe36Q8m+
z)c<!LX~Kk`YTW|DEuF{pUT>NpW|wLWv534ZUulGk^p|H4+F&pW|MTK!JMEE@KGT?-
z9DX~ax8t*xA$oA;szsz&wX9<d3T!%IFe;hk-+74S%H^Yo=;m}NT7&_l*CjQczA3uQ
ztTh^OK1M1ifHdIdFFanDm(+ai!EEpyIwqMIcl{RNDN_mZ>IAW39XUE+m^T%FZKl+U
zt*}YbS&*mWfsFLDrYUF0MMww+AP{MTVY;UcvNV0ONs;B!!uP95jjJSkdL;aw-{nCb
zWaoi@Bvv+AnGL%z8+vXrHCg}ccWLeJEOh?<>D%~F@vjkG9MwdPxl=8d7Oy<2E_EdI
zZ`nfAd$JG!D(9F<{PDw?ZjUqoq^SF?A25Lp*q}^IC_ok`;{=yr_4m+fNy8OFSO4k5
z_)xFhv};Fn6Z-O!nMufP03?K|?6j!_XmD7Zo#znH>z1OGb%v!!sh-zeABGMuizg2)
zkAynb6MnZczb8&uA!?}C`knVufOP-w$_D&+w2A^HI4qFU8UJ%5xjg*BiA}Z|9pCdt
zFY+W>30;6$jAFF0h4s6X3Oz|hneur9TIF`mel!1|O<KCNyF12s>=hMn!^-tUedzF-
zlLxFsMm>`dFHkrYSW#y!k0C+w^)fr_o~I{V2@whk#=0aJut4>f9w>fZ*iM<(FS~LW
zuvaSLAVCwmhR=hSksbB8`@n|)08M+9eb)~^O4_;@hHLIP`WF+<T4-I#$*De#&m~f~
z2Ms?grp+`IcBrQ5TUFlxj@|IMbULYq#g;u#E{B%3&hGfczTfqYsl{pwVJQo;-lYY4
z-&w`#I#T~VWmzn{Ffp=)ybSEm%dh^XNp&CzSi))LBuKj#88T}M8kWoojE;+y<gp*O
z(5jrtBtnB<Zd`lbzk*s!9)(FOMWOY|Bu8EyBl8zpOVKFnbf`yUsAw0EZ9~zXzbC~e
z#^Ye&Go3VMXW}FvMCbX>LcT}ex<?>qDfkbmz9~JwSY#(bLK`YCECN_YB69sf^P(w~
zJGkymQpFiH>dFuS3A_JY*+lgzTvFE-78c+tm2#UMJ6jk(1+~s^YzXVHk}p3y@wc7u
z{5kW7Qa*~0ak50hpF2wt=d+l@Qfmp2G*uN-48~C7Bw#V>tndh2r3X{Dy+VjNmNdtH
zgRWndNNjGm;!@GqUsDkW)3@m?q-EafQRHIU{nl%;;Xy<~nqT@&De(=x8f%$WOOWNf
z=fy=!SGVPaQb0&0pBo_r;@D;;C%RQ@q04ztk?kGlKa;~uc+|@6`FhW-YJcvZVb;BG
z(T0aVi`6SEWTHBUrR#dFN%GX|fH8rtKi*K4V6ljO;4stE{kBmo^3a?*Rlye?w+|1H
z*(>MK5%UA(gI09h2*0BlI3g3t_<s;*Jl4M!O3$E#$>Su_LY;p<A{`!~+d1RgmaGMJ
zm~<1#-IMe?`))?HK!O{Lx(WTCx|juIqXH^y<JHwoSV2FC;vhR^<z#k)ru{ob!jO_D
zsTpX&Eef~Uv#K8EBy&S!GEq8Zq<>CN?qWsblccnyp^Yr|cCP0HP%@{~d2<lYA=3)j
z2%@Cn&4`GcWm~<iJnN)fdaJ7F&MLA^26H$pvHy2BxMGO^_Ko$|e*vUtH@sl_tNEDO
z{e`j?$k3;%7d71gi@8~8YMbJ^8nR7Mrf0LT&+K5-d>kcqP4_I+w<#3ufqg9Se1ir1
ziPv`;`q712jb~lPOUfbW?0y_$<mk??Mf7mA36Y@@<#@F?4LoxWcYwD&BI{n~_Vxi_
zrB(PnBz3HCBsP-c2+uG0pLG%5KHMV~V<#ogsBrV}G(pT}7y3aiYG?WZ5~dX3nU6U0
zxGLbP6bsj4bi)Kt?K1t!Ebhh;=Hl2CeHW*v0(Nz-=;BRLB=g5Bh)4<exApqHxb-ac
zKoZ}^lcJQW=W6XFHYrZlQW5JF`c@lH3u&;WBiqJ<A%dBS)d<ngI+4NgPjrOEsz@T@
zCaqF_|GK<_qLjM=0pOqyS9a~22sZU@4}Z|MokQy14!`Tz2sh#&xa7~DYFk7|4Y=ri
zuzXu<+rvM5oDKazYi;$p#?#~=%r#Zh;U6VTV0BknGgvpDJ25AZK!FG<=mXu#*0`l0
zUiFZs9JBHK{sJlr{Xz~s0WIw`X9w(yPSP18pk5Oe@vcALR+pEn)>>?5L+kZh4wr#>
z+$>b6Zkhk9l7J#s_P1_+q4(vqSjfSj8C~ANtr)ii!TK$54bqbNQhXr0^Mo_M+buTl
z$NmGf)gq!=sW}eJkL^jfNf)TnQsuN#5S}fJIh7{#r@u9lFj_|B6*e@GoUr82;mc=x
zb*$DxcLDQDc&Wd!$Z-NHl0S{5Sx?Sy+uEv}H6JL>&#fh@m)ZM^kg%YjSlmD`gfjFk
zFKx#>w7bXz1PChGaPf+^WAN}SKAs?j%IX>-9ZnTSM|s*>jD369^;iMWVG2`uLTKGS
zP7#v_Rv<=*v3~LUEOFnN(kMuy4h|OctA&ac>V9umRW`vjArAWm>OV&Z`!_{JNkedG
zmbsv9%h8mf$<R=QVCm_`RcP|t*g~}-D{lApFHW)6g>0~=er#4=s{_cL^npxg>4H|?
z#K`lmY_J^x5PJ6OO;_%IkMnX@KbaZ^&3&6mntB_^JV%-i3;7|kmw`+7!|u24^U-@>
zKB|vL_e%Cu7B&$t1D;CNyl4)~vC@hf48^Qigb|^<-8;DQXR#TJm(=`x#O@ro{94hJ
zU^vwM`53bBEvG1^>Ztk-G#VP);$QZ=?t$pP@t*=H=9E_r3uL3<(@j7IJj^;Q7W<_b
z=1JICX<nk0@9!aZz>uO34j^fK0rVl$WcJflMV}yqRQ}&SyGr50d5%KF`|8H;%KK^K
z@$#kTdw8#_>&nOIM{sZR&fLP~4-7RzzCea%-R+bp-yl@kNthFda1Hm*pQlQ^y9?L}
zr}u84qg#*9J^HsT;Z7*+<e_lW95Yqf*y~9kk_ZVG((bzEn7}DzKMd1$5ak1!px5$I
z`5gB#X)6ydVypF7qf40^C(mVrwRwDQz4jBfUt!m}zc<<a_2_wdCW2({Dn^y3(K0B*
zRp;Qy$rQosEim>wYFkz}HAU(eL+F(SpKq~F^?IYIbGq$mQOsm!n(e;&%TJCEcf}(@
zgg~Ylfa1Ck*#)fkthl-PimN*CPL?<0e~pabi-ZU-G|QHJt3;JUB^?$aIzQN>*Nnv3
z?A`QxxzjD-A~3@ntHF8OM@q~85~WREIg>kGyZz#GX0C~>E&s7hwzv3ID}w&A#u{Dm
zBb&3hIq4jX^39JUc!s%7zYXy}iUa+9OK~y$&C%4@mPnxcq;rSaNfrwv*hN}KrXmOa
zwp0T20pRap_|M*u`EyZNk_$k70DpRZpDvZdA>%QRC;^vcpmN$(N;#SoLLq$W$U~x*
zhur_S-fwN}oy%P;Na=2N&wC~Q9+!N<5M*tfqa6&qh#5Pa<)rKZE^B9&;rS&9T8^5y
z)-SnuBzSnUxx2?Xj~Ko0G0>gE-9Kk$bY$WGTLp2d`qI+UegK&7!4uG~3e7K0;x`}G
zF8bUr>%~GUI?4nNN<E44R@#ndX2)2+-?&rTDia1l)meyRLpA@?ZlPhuvwgDHHvkD{
z<8g**Pye0+<w>ex<c^(%kDW_~hQbAj^8A9((6AWh!HHRDMuc@NS2APIVP~_2sGQA-
z8Z5Qwx&K+4!|M$@MT_;?di#xUaA`SZ`l2UdOzeeUV?k5R&{HKS23B1i!_RG>idmuU
zruV_^+gD71o0gFu!PVbH<!r30g>|DSn~anAQJd4-1W4#vnMQst)~d0*;~Ko!+BdAN
z1ppxo0)qYK#=r*`z?Zpu#U?sHo_gQZRRg1(bO*SsgmmhR;(lIhKn%a^K6J_y`Q@q<
zFP{)>%zoj5%Y~FC6ZA*+-SVfqzPX;GYsZWHpycBa7-T?76V?L@d6TygFJx9Ex&Q;&
zzpSsb2i_ACi}^q@OiTb{9C)?@-jp|hUYNYR0&Xz}YS~y~jAA~V2Ts}B^-8Zr^E^|W
z8M@h>KV0WH<RSoYCBWMm85?V6X;P^T+dKrz+J;;4l#JTD6JIGP%q0YK!T<65_s5)A
z%pD)1t&^1-RyzLXq-A}#_3moh+n@l*1$ID=$;lXePDQ6Hq=G(9K_@Tbjw7kAbv@iq
zPDw!%zWc4|IN~`CgyjBLF#=`%7#;DO$b9$5{YPKN!{T<(<iT+Y{KtBvz$6-T=#JwL
zvb^5!f!ps;-BV39QZ6y#x<%6n5v=r}ID+0_UI@1eWM&5H#?;Vb&u09Lu_K@vN=4cW
zDS?3h^`4T-IRm6ZlEdxJ4KxQzn@bHql46>erI!2b!G}&Wq?oZS54TNm5km)(76FXR
zOY)t=qQckxP{($T80!!HcDw^;*9bcmQWlbwArCQPr44O3Hnj*TBKPF+3GtVMH#|LF
zWH@*U%`G_9U%%Q!L_8tknQsA}qJO6n9tMnTV_1)sf>bT5@ey!nJM*)`@qpC;V&)ck
zt}yg)cE#<YcYJC}(%Tw_@#m!8epU_co=}c8aoXY+VQ)c7OG~$ZEAG;Ib)CAcR5hG?
z=&swXG#RldpI}imFb%@LXIImW2lV_NiVQ|D`U&I6Wji}sy(QXNzzQMmywc)`*7thX
z;32X39vtYt9Q?4m^DdRcY0sHVDjL~W=yIq$d5cu)11*W^Oq+m!n@%7bK`NR}@}-!6
zI{;-ycljm+IyS9z=^8p_z^6Z^a*Z&D$E5m}cHS1&{acVlH!MC?DRdB8|Gqorg2N87
z;FTAP4cEeOmy&`C=Fv1nRr+ZWl--G)Oo#-=0v8R~ksTj^q^fRlZTyI#fN*hiJQ?18
zJ>+{_>gbdC68m%f|J<Ed3~}x4ypuPxVnr{*Kte?6%kig_jSUKL!t-&KSm^uN_WR`z
zClM07`WM#C%Renlq>s-Z6)8pP(jP8PP8*G$M=F2*{AqOhUA!I<&*H2wyL5s!$OK|q
z-TWz|nK&Vd^KQ~%2*#@d4FI;wpgDVLO~~4T$fDO9v@6$-XH&rX5kVI6A@?|m)KF5}
zfkoRACBaI=B-Gt4psAQgJ-IoLHA*4MpbmBvF?o8~7BF;d{?Zh%_-R;LW`E?zk8l7P
zmCs5qu5)OY;pNrn0Fb_@N0W(?5);+u;O&07c9i@JV$pyB8-KUJp)9q)HyV?c+Yf<&
zF7m%8=zKXl288Ek(Bu=HN@;Tsq@!*F&N{24sx996k0a770O|r`2$gV;3c<_(r7WZx
z(C`i}S3J3XX7|^kRUsBmEZgI-eHYH>55nFbd7!JREbS_x_}yJ{>V#k2yE38FA6zfX
zD0=f$jMx=1|1n|l^f{?$U@Q2-ay6}@`fK$t0mQ$S=H^Dv7oQAl+~Pl87%C)!{lt3O
z{bWB!Yhi(Kx3whG{W_(%pN=f7@Jz_9cSlKmi8SZ{dU#|cwhue_;A-g53yLt9ewP?*
zQnfoFW!nH6c2Ia{qNgQ&FT~ABgr$}y=yGF|RN~iwc1cW(m6o)Cv`uj4?e46E<PWZd
z$I(98!Cn4&?4B-n>&rpifA<vhoSd8t0onRLuUS#@WkB!0wY4>;D<_SB{lny$!?h{A
zck6vc?J6|3&)Zx%%=e2aAxFBkWKZ`W24(v~qEkLK_;uUohmurTFNoH}Jd6`P;O4Mi
zNIOB89V9>F%g>mS;t}~zp2a-)Zm)9~+`n}#uF|6Xd~doR?>^qyCgcAi+Z^A)s(i}I
z$k^#aA<}~|e@HH<7W75^Wjie?*#pc!UWbfW?RS6$Ca4boeGPit5S_~9Lxc0V7@jDj
zyX?0Wi&*=|czd^AexI3%%%At=3r0G6%KG^l_%TBZLX9UslSN1~u?MTG)A|jtqWN=v
zLPT7JrxXds{somxESh)`@&N~#T62|sRAj5$e*P}nnXht=23ckRA*^7?JN^mT0J@hH
z_GHu8I2Ik8j5PKtdV7D{zqCF337X4xS~g*&id+?w)ov2CGD)$$i)(~qcA_xBcRPT{
z_{_OvA`;QKpuovBUm$>+kdVmz<g5b_V_<D3e?A5guXMv1xQ9?uG0Q8GCH&`KBx{Dw
za}duByI*JOcYUtrmNxXV6EqFCOE(5za!QY?;9*7Q`i0Jl*4VKBc^+*aEk|OWA*qpl
z?DU&SfKPypo5$4~E*~KzfO3?^p3+IkNgSr+<wb?%kf_GMN-9l5%*fImwDD~kknPFQ
z0`4Xh+<z%+w{}ok{%O}PhP12(eMbL(>i{sXc|zl)zTMH8`VH8hSeF+s*#%FYzg%<q
ziaza=p}{!q@9z^81^i<$+L~5sPPl`iHme|P%tX;ZM1N}!;Xgy|++>A*m5@IEox|mb
ziRdwjPGmg@bUoZp=iIdl8>Fp*1cfC;?nwk_*YaQ<<IGH$X<(3$5Y2q~-Cm4+H8xW~
zO;LV#2iX`TBvGq3hwSk67{w24q3>J)>q6#n$)iI>AHp;Ff^p|FtQol3=9Q1%dZ^&$
zw-@6o4{3*KX)H(1Iw+_-xow^5ZJ1_0BSe5U&RFX67dN_(f`wmmld8W}OB&h=EpTyR
zWaFm*M)|#h={)n3^Qa-0h~9?0mKupnS#XEE$+>UbepdNhtC1O=)f^h&BlcKY#J9Iz
zZh(qGwb*)ns{U3p+O$7LVD;1AK%gk#Gw!!f7VEOHmUKirA{Q6dEM{#g3E(lTpSKQf
z|ArNUu9!>*vV8d{cxVWwo$JRZC#{J;jUsn!H4y^i0Wih6a6cX+LapQBL;0K)Y25wo
zf1m`E9S0H}&VEVg(gZaBeA#{y7H}<=<!IuF=%R$ZsRD1(`Xh}LYP*omkQw`+g9e2L
z$f&f5nwB=s6Mw+0NDE7tl<j-KvwHA5^7XL4Gj8w&*5eny9$ARA)t-F~ywB#zz%lV3
z$g&~ij>#JO|5VGz3>gChgAcA*;WCYYy~Csj)Au_~*VkvV_q=0-+l${#zv9InT-kys
z9Dnv`W;@!l;}fUTncCayX~@kvc)`O8Bag214D3s~s^V?1LU@F`;KMZDK`#Pj^l(St
zGj!imJ=wmJzChvY=yC}L_-?V|LA;Dt(w1}3iZ+G?&DMpX>?dxI1lf1NwGmr+?*X(b
zP_*ZvwWYZVDq$Ys)e=y7xm*n7%$KFE8>AGfkU4ysWOp5)JY8!dsY)Rmib!#l?gROm
zv_U+GUh7krR}G$^k`H3WjjkC0C~}-O?>4tU<3@P3L(jnZ-)af*&74+8Q$wGr<Qna+
zAeoK7#||8KU-UpVY)+7Gv)w0Tl#e&_Io{eS6>{QS^t|zgtH7P~HAlOsHILJ%op=Z|
zIxR9<*;wuLP8(kRG&R|)W2s@X8;*ge#0-|g$!PWAq39&S!ed*j7q^z7Vf@NCzqAm(
zzSJQ1(8J36oxjnQOsn;a3ht1Fq}ypf#4vn+Fp%46U$PD~_FE02{P`skLGy5M>1g;T
zP3_e)k!vGguCzAD(?MZ*89+bjYbWWoz#>&u_0O-PK@m50ii``X)6aCL@PtWe16YON
zy}<F+r1*R2)aBYobKD)Dz4D2=RtZ=P3t5oi52z!ee*#q73u}yhnq#4S_{xxaM6lrc
z{QjlCUISB8Q^HrL05|aemry&OEPj!_ABeTT{T2Jre}7mA{BgT6wEc0$*A@^F$lpHu
z-1<lS;07Lh537G9>AcY7QC>{DpBtLz^pp3tNJmLeGb&C6O@3HDzdho0g34aaMMw&S
z5qWitO1)))v4#vgJ_}}p7HcEs$Na*3Lg+gZ;6fgdLfeQrKWFXfeqzx=y2L>@<7U)I
zsYp0XIIDJheY7VQ@j_1tzDkHyNt82HWSYUv-a|4C3TL`!D63mM(W5+Vt2dlCGGx2o
zl<7{${Z+YBs~Q5dp0^@=p&vIw&B*%RlU(<v{z{&PhO(`#8_cVjqBU$!_NP0=IG3Ka
z{^jBb{-<@i(uJkKV4qJQ>f4@iW(QbSwK3tTr<Y+N%3FX5WbO5aYN36w5Nub*JacKk
zBUKsi5hI-f86xc4_4K|bwED8>FyVbx&gUeEK_wj+jw9jsxTPlzcvQ#6#V*xVf{u;e
z!4u~a<5OK2LXj8jYA(mGk;!LalVj=nyt;;gcMxrIfnBAhL=SzLu{lfsOA$LhvfPhY
z$Q@Hc4tLacxOn?wIIeV>-!u@{r6`?(|1Vy8{uh4aCKeQAK^E>(5p@bB$W|NcBs|bk
zETE3Bkho+N)MLH`haddTccIG@Q#;HhC2X_VL8MBu>gr?V;NZ9{BYU$ucl%HQ0)Q%2
zT=A!ufHFI%2=`xCa7Q8n2gT*~7&C&$KR<n0sFw_bAS~k#w#j!5$+#3nzg`n%O-)T7
z2M340ZnoMPoqa1G&mX}e#2cdbs-chnnqT^^$7-Ebb$S6mAKN7W(FN-`z>)nr{sD$F
z$&PWh6>))s(%hS)9hI^8cU!~XNQWodKm-(HNbfgZ81I)Grt|Y>R*qZWNW1Z0O7+df
zaWXarf=tMM8z8LMO9nKw=8FKtzq;N7+$AF#f^UW2eDvyVu7X`=l<w~Y^c|SA6U$)V
z2yXB1ipyJb>V16?$aCpH1{NBevPmS<;z1WP#`G*~nH$5g>brDqm2w(RkhDoeDV5K#
zJ>A|!PCi5cOh|U-HEN~TlE~ITp&`qvj-E!y(TCS@gH+Hf2Wj%W=g4K4hT80Jvo$~4
zS{Ub-uv99;SRXgL4^iT^j+CdGH2VlA{nKpmUfFgi++cKS?MVGO{9ELJ$;qGUIw82G
zPyd$no_7CCXr}!OJN8YO2zLo(l1xTJ_UIy8bsD03#)?gjt#FWPZR6X0ED4U~T!R)q
zlMFC`W~>z~#@)$o^UYPQ#T?s4Gfg0~Tu7f=v60%%<+Mu_eAK4B6(VLvsH&W56ddng
zaw1=4<FWNrI2$zMHrtD2kXI&wY2iV%#yN67T|v-_>!a9E&KiLDVWkHVxsDAdnX(i6
zp#!XkJ=ub*)0Ww0Q*Q%<FPvZLOQh+mFBfQGduC=-T3cI-O{Sg`X0UewWL@Lk`i`3*
zD`cndRtQ}m@U}g8z5xa|;?ny1>DT`fD~vk5e7gB7?+;@pZwGv#M36D>V<ER=4a{9f
zaYqf-L}B9MXXqeVR(`@;E^hq`yO^=RRvnyeAoX;*M2TQeAxdUi;pg!;exF8sf0(Mz
zEq+ZPRoMKWOwn8D6KgeL#jpl@_W!&gf7#>jJnNT!+AH}v%Q4U4cUcnC6g-BCjs0in
zq<#N<ecAjzfAw+E^&L%wWE0ZpubS?1EFwg)u*GSTaxC5s18O?0>d5Dzn4Q08QvUV~
z7U_FegGDCbh7QwHRZ!W2=KR(Iz>Un|w#m-Q*b{r-7gN{LpaeSzGcl<x@jqy>BI9y-
zy2w@7?v;#@Mr;%HA1dd$uNU~n{y5rIa_7KhF^%Rk35DXSR35t};8NF09Rq9BFS(m8
z_+5B+xl1&NBZjJF{nbF&A*HzI!azAXDZciDQDYkkP7xV&fCpqF%!khw5SS^z<X@yF
zKsFQdMI|K4n_r!WRmfJx(ZENFB%X$xqAV8Wl#@<vf_qSJ1?8IrqH!CD1QmkzO84hB
zPjKHT*Qz6&vPy7Y4m`fQ_kANU_#t)rLoOe0e#^3|HX-5f_(5U@R;;F?zTwZqUq9|(
zf374;N@@^3KO6hG9!X#)SYG)F?}^$<N(P;Rd)d_~;nftm_lvoM5u?SRe7cP@i;6z}
z<O_Iiwdye&|DOoG_lua@Y(iiEdZBWPIZQ9$TSF}#)E2><ayXdT8bv;UhJJQ`$fhzl
zIM{E0nom#X5Xtm0oVu?5KWl<}lDc75_S>Fn-=$<~+jnqG=;gYr2~%eUx@D>m7uQX*
z<>%#-FilV&c$*GfLr4pe*mra0y0eOBD&Zaip%`PGG%cyDjPQOY76RKQ3&(@-LWBaT
zg%7`oa_O@=lE6#&bA$7Zg53J<`Q>FbE8EH3p1BSG4mr8bM#N@1CpoQDLt0jUZt+)A
zNFGwl;q+K34%4pN_c^xFCBvoqu|vKsac^s!tZzmXqC{~aF-RTTeT0*`b^YIrFD!4e
zoGm`I?EW5y|I&?)O2{@l%onJ}C2whMg$Cw|;)n|&Ui94HYH)F?N#_3E)428WrTXv^
z1wcMChiF>Av#7!DrJ&_=cT2U5(D)38ia;6hg{*_7qVg82d%*}np6&|eJWdoQSAC?~
z$8X#3vmb+7^I?63CR(u<RE2D-M~8o=EJq;(Mlmk#e@~PJeYpGQ=c8oVA*4}2Ke);N
z%A#Zt$bIT{PVzpsbMAljZxO(%)hLkg${-c#oz6eA#zJU1DvvHXbZP`0LP7^_N*vdS
zE1ks*{E1q1K=;#`l*P^Hs)&mpagy<}Lay<;EI;hu-A8_RM&)zw{+yaRKAW+4|MaSX
z=O(cWrZ=#&z#$(0qj7tCTWuQfx59Qbk-+m5Fmg59Z8Vw>0hohN^j8XqggNkyY3oSV
zK)EzIyyFpXlV#`R0<CbUULw(Hvumcvj5oXagi^TJ_q3D;q*OSwSd1&Z+A;Zp$5m|h
zx{UuOrHB#-Z*t7O?!UP{_mGOb1#a4gUM3togx;Z%*%-#f#d(W8&!@18kz(ReplfJ=
zzl5<~i7wam!c?i^>>mAiMfu+C3?8L^|8`UnWKeP)!Cxi#xDj$_a_v`xsz3XcW(edh
z&mvywOd=G5c;eEFl8IycIX4SbI}!=>8j5wn29R=hNy_qg{WtA_I+Uy&1i_H-v}1Io
zt&KS?CHnhgrR}ZZD7ZTHMo}aeE_)TPIo0%){OD&~yu5^5hclMhO@-&I85u<*ogDk-
z7Z*eKEO{{F1u3n6ydbV$f%~*IR#e4g7P&5HBZe#>Htgo}kQ}?~IWgdVf?7P9QGn59
zY<GrdfRv|2m1w)Cyn%I;hTemD1dwRLTcM$3l`2JHoh#5Qf<m2k%omRc!tYURW=G$Q
z@iV`~Po!6wy|kZQ^26|>bfV*s#0j(<mX>!)ZxlJDg|LSWfy;Y}G1AdI$f*9-bCit%
zSXYU}5f*W85Ql>0Fvsjzi4<JPJnSE=0khmnd}u!r6*fo<Nh$6acujN!4ne(P0XKfA
z#uvy}(XQ0_Pog!{c5SrS*}8jL@9GdrFP+DUT5NSXOq#SSSpw8Gvf|mZ_cXcd38pDV
zc5GbzZ3z%61OP>8*xE+m<eyJjNlDlMv-Sz8hzE9oaRIWM0N05RhpiJmd(bo=ebe;z
z`+diM^V1eIaDJv>^7%^3%6{i_TDg>}pmT|z==jGb7V^qgpnTMFyv>!p+4i*M`o0`n
zNTdO0<{(M`Alu+`CPLqDMWjGpT;B^9PzGwtg2z|3fxv#*_4;ncP1G5ch4{Ic0Ms%i
zg(AOC%d)5lV+Sc*(|Y{xEPC2{>~^(9T{8gI8%3Gl?U6nowFuP8;P-ewJ3uW?$<mQG
zjZs}wJ0c1JG9)tO0A}<~<^6z1IdX8XEJg>!1<Ac?b$T(wsO<N9&g6W-s8blE#-It0
z+XRjx{%@ADDY98B7rhr3gR2V~ek3l^x%H59tRq>@>+JT|(*MQ#!zL^wq&&GC_f_!u
zAntgM-21-A^SCh#ed-7U-MC_;J!(Y7cLENtTZoC+xcx$YZ$@DJTZGvAx$iO78#WeJ
z#N)8v??O#a*d=?<VsRzX(S*RE<g<0R*KrJ$%HvkXsfog*+0efU@}J~KTS8w&gtDJ{
zBn}0nXl&)%*yToxbv9-(VNy-MyYVsyR6)1HfM<SA4Sy?8c?=@8OQHop)jbe?3_=%Z
zoX+C;tiyVD^6?yl)pt!3Qjs*U2oqi*$~m0Qgu<oD`uZ@4v&2~2i{po6pVgtASmx|o
zuczp5v3DprImgW|Rk2VqGumkUc}n}|9u~YMF#ywn-}M9?8TPC<&<tZN`ERa^g_-Y)
zdSG9cUsQEXjf8?d!rJ=!yfUgF<c>x(kI{uc_4q~Wv<-*ey9%<0*n0=r4QKNIS>ZDG
zR<eEwoA|li7~cwtdV5Xpi@i_oGiLsiLeuc+7GV?<BlA3*3X=hM4n)L3BQJSn*lVAt
z|C&o)8|8&CK%PTvwC9m)nqjtPs{f3E?4V^t!ggk$#^M|SN-i|<+*6w_W~@fAIDKr=
z`|c%B3->tU%RFI}Y|&);f<`JO9fawk--vvrz%a!?v%YmWO6#=UgF~t-_6k||B<!P=
zkzqDaN`o(A4#^lF4@@bgU^Z$;Hr(<ffwhDNgh)EGn*cTMKGYfpg&a<EN>mcz$TY4f
zH-VRug|E3o0YED?v4{iZuf4tBe%o?tAqOH841EEYBQIbwHdQmx8eHme@~qWSki|PK
ztF?AE3SdI#v@8zYXbutKl(Porc0d>Oiu6F{6o|mR04_d5N2F2Ze0Wne%z2tQ-|I&N
zh%II0SECR(*A!ax^eUx+$cc0qc(k4OKvIj2w)^BQ_WdLf-VsfCc}Yh%Ruz&81(mrd
zCg-mmAGo>25Ylen3-B_Ncy0d>X?H<-r^9ss*3n!s9=X~<ghGQv#t6NM<FIW6yPPxy
zizBiZwGb}J7>pI2Do$*m9#WB9ubo{Rq5gA1!nowCLuoks9k`!IF&l<Ly?61I@4J)2
z=P(^uT9q$g*Pu6|p!yu8N;AMpPBiqkPJp=+kHz`?pX*^XiKu}b9=Laq`A0`^HQ%NJ
zAQx0(ab4AHe5Ext6O)<ON;5mP>z2H!sFw)oXfjx}+B7RyEu&3Fh0;eU7}V1<mXN<%
z;*H)XI`<5^N?IA6`en7XledR}`zhq(?IG0lKf{Yr@U3?{b^22M>&5Kb<7^S1+^Co7
zEN@^y0OsE<QJbk83JBJ}zrQFQrk-Shr3^@*v>63UmA=M1`#`bh*)gmm#Dx{3;)w1_
zVqicKYmYNaPA?d=mW#Omvtrh7hW4lPoTsOKp9BDUkt6YKC$3TR<q}SkkWMOO$dD^*
zYX(<aLKizhcLE$)f|r+459S*=^L{7w%JdAi!}Ae=K!29=a92mCKx*cC<Z(~854mAI
z!t=-xy(k9^fIs$zo2cj+g`o_KlDOi_S~%TbM0{iK<vwQ{k{6;`nA`{D*YYbetu(Ga
zyB`BQB4gG^Vio(p#v4Mnge2QiS|xQX5ypf!Z3e@mV*{+umTR{JE8T%;%_G#Mdqy-{
zAurBOL4VA#adAq^YOw?$HJgwP#lN$urA2kNXKYrAR>etWa9|cd;xFs!#vz2qO;gL-
z+90I*BQqB0Ye>VN{d)T6kU05M(tAk2DbN*fG-Wnis94U@k?(up%kTsOyLDtqy)4U2
zUYM(1Kp4n-&*)1MVY@YN!USw@0~c`1I}*3FM44G$8nE$g9{N%w9>i`%NBk{boDsu8
z;W+_mXSjaaf}2u49WpcJMbWa@@{)?n6C2RCF3jiCqGIFXh~~Fvf%pIz#!+9NAOe;q
zqjUAYE3R30_jmWladRzgZFdP>Usb+<zyN(nS=a`u%*@QtKTu#D;XhMO;A}fc3$ukA
z*KsV5(h`Z&16`BRj2caL{{^c9X-0R==p1y1o9k=R&bRyZ4=LcT!wOVV9U)S$h5@}k
z`(m#T|8?~?VlQYO7|SMr3z0z*Z#iVK&5k02FyRS&>s+9dF_DH9d`Hn@R6kixTCvT`
z(mdc%Pz8-?1FVp-`!jx1b(;PoKcMeo`AaCTG3ZIdBzXB)ITkb4Wo&8M?yDFY8cvUY
z0rE9q)QlcM@?Zz778$zvQr6Z4>klf0q9j$Gsuo9w)A(YRf|%(VFyzD$Ut11Vf^NNm
zt1UcON#6$I5Lu8p2lzYAD_}cCfSZ>Yd#2^F<TF?vhb%pdjYDyKGkL2%WADiGFKpk6
zWCMLR11y~Mh9-QAzO~vD^>TK)+G1z#Gz^s@8vYAL1~BH1Gy@Q|yWWT47iA3!+|^Cg
zjVd7cFB`0|EoIi!+eSc#N;WX;uFt%fm4iP3i#(OPNFYhDQ~YSe^bCW)1ZR8+Pwvmy
zflmkw@mi$sG?w69nTyOImS2^ur7b43Vlm_i(_9$EIpSsHRS`}I%u<cAq`QXcbl&+f
zLN`2ca>Lmc3F0WyIn>f@me-Jnho&L2NHUm4L>K#5oxLgo+8xJE4ZC|1X@q$^wiKct
z6;%Mj6Oz4)Pb+9?ZSCv(v}=gxx#9NnlCy$>f~_3!e<zn52{%~dFw+kDz#{eE`57+P
z;!W`Z4{Qq%x^v4&z=36XCWJL3LbcM)ADN3AP$v9i539<EXp(}5+6}dMw%Fs!jC1Hk
zK}7|{WiusiTAVUaucZBW@$s-dHKEO22{?k{21+SiKjM2tT!qCO;=Z^YWq-VFM_YE!
z&(AxzaxxXhydtZvjPO_Cp+PokX!o$y$t#qS&i&c6<7WTJqPrj1iQ?d**Pe5P+4;g@
z%WE@LNCROSLHfC=Nv|bDWUY#if=Yzs<^C)}0o3r*^Qh5j#KQ@X{L09kA^#ic>t)RL
z(Ea~M)LBNw*+g5qarfXJ+%34fOVHpB!D)g8mk-zA1b26bU_nA~cXw;tb>7^WyXGH%
zSgTie)v2m;_I@_$N_<8}SZ+`7?X9xsK~@!?F<nn8$UG^pXrR`Ht0eEjl?>29{jmA=
z(b5a>zg!zHQHU2^QGNU!{U(B-kCNETye7Nu^Qd(y=qd%Wg(+6eg11wG-A=^DWWH0>
zL@~Neq^P3)R)kDy9T3BmFGYUm?#7|!)|N@n!qB_gcKwBu(|g^Agx@p%9N`jN$LIG#
z0Nlta#Tqa=JkAJeFOgM$581-(q8BgNOfiG%r9ohCW2T=g<9$~66xyd13pHj$Fpv+B
z;?S|dU(m1}aJg>I#iXpns}OhCSKAc(8R9u+y1`-`v-ev)7XNV~Q*kdZ#(J4JNkv7b
zE0l@w2ubb?o-`#qR*Hh_bJsSCzmlc!cN*ifBL`XUtVZi@3x;Oi>9uKEwbX>Q%+{PY
z<)BKlX+TmAfXJ<I@Ef-Vnu?AO4+*HUZ+WSMne=ZNm$MY2U5A!byy9)4z!v%g7%>m^
zpDNCdj>Mge*)WP>v0(yxdU7eoK8EoMGQsGMfBBEI;VQT*qtGD}9mx}iG)RmO%Ap+!
zlO7`uNc0FNWH1{5$@(X9k-{!+e7`3Zy4jSBL;~1PhT(SeZ!<Y>u7I`_O~GmPA@_HE
z%iBFdcl^8WhDP^GSFc4K#-C;uJjL_rB1N`mLZaudSEPvLTlFg@Jj8AB;hc$#?ga^`
z#4mo(T7iKaN~GnvC14fvPjyTSLDDGS?N>Xzc~#HIzuQy6<iSH}3jWNfwLVZGKot<W
znk=a8A4D`Mku_AVBG7?UT6S2?F|v9xF*62EnOVqJ<xi`-y55^Pj!Q5b)PIO^yLEnk
zX19F$l(dhVcV@uNL>u4CV$)jPVJ^HskrUVbdV5aK${IXDE|yLZObiDIe7VTtgx~lY
z&2pNZ)`s2Nq)4>js3YNOS}G(Juf&gplR;roDJ;F2OW$feCdk|+3%d8Rg(4>Wwvc{x
z`;+6beHmhpPkDVM<F)q{_H-Jdeei{X_jtp!WPLG`Vf&jDL<eLsR_M5Te4^wKfx-Es
zD*auTX-2_-jGTm3;p~uqg_Q}XwEsV;7bHizsqNM6bH=o2fiEmpHjW=-e~gEyWU@BM
z#{tx|j}Drli}<+c<P-Rb;XXG}-nB+Gvi3gA%(QlgWRQcM0^dSk^4tPg%L+53#j8S@
zg26S9bw!%c!y|i1J(4NhmwbO;IYng|Gj*b(Zkk)9b*HWc_%W+*EuME9m;s8$)Lm+X
zHc13`6u2-y=djbNDr(Flp{9^a5i7g$vU|-RM%`<bPMs~S_5wp5>XVXbI`!`4Fy!!}
zHFIT5GQ^l6Y=L@9{ady{@QFa~*?z_pT5$cZ-gvxC<M$^WZOt!TK5Z_a0ZvB911aqG
z&Q3*g_QThY9t#y1Ic&n*aYm|{9WEQ0TKAo9RNXm+RrD<7NagAIJtPWM{dvjoCf~uj
z1Jc?eOQT{hhD<%5wYBl^m<^eGs*z=5N&DKa8b&RP+{5l5e;}Wy=!eEajH25FF25^a
z+OKq>RXBCxIzY1iNlOhoTBx|Ga30}8*om2$Pv(~9C<7eu1tZtI?mIKT3vWyY)Dad;
zPA$dO+0Eyc75_l<EN5h5_ZLUMQpxIRjo9HZKmIV9&5dKZmppmcI7E~fXgQ+&k(Pn*
z`JPN{FWrn|e5Jn*UPAk~cmxj984Q$`Sb&)5b@;*FsBCJhe^GJC)?vg>czE=#1iyAd
z?GpHOh|*#rJ7g?_2Vmw505-%RE3om54YWO7ChJr2osVz@$B>W_tAU2Ri@9dBwC)Td
z)V^V}h*Fk73WvLrCcK$BXa7Ou=50HTc7t9qf?Ay}eXj%%JnTf9n1(7vXv(2zl0@H%
z9+rB9q5YG-zaJ@=T*}XsBQ|GP*26<|hB@DS8w<-c@HqduDk*Kt-ft*EdE8!6Cy3Ei
zyc82ZH6VHv)wQK5QeFaNRX~|!Gyhx4(GHpdK{QPb?d4dfJCgJcY+ou0i~?{hbAYTv
zT(B37h!T8IFR7&gFgKl_*Zz>nDyHRzD=<JIqxb*}i}z=Sb!VJ6`7+a&E-IP7S@nTf
z0+sonm*<uSTufo>_oC}Yb6#u3H`DBEfQUP!8WsDAldXFOoR<as_sFA}l5g68)xt3a
zvm3!pRds@3cr$V%T=wV(F`qj;^fAkXQ7+Z$J;d10pRZ+Oem>>$<$7W#f-ajvc~x9g
z^4#u5rc~Z^(B6!fHNg-KIkyD8oKJ&^&<<%+N*;P!BeIU0n}sw&Uf#^$yf30acIt~h
zM#~5llypqwA3a9A6Gx|kPy}9zkBrD@+)eDr@rs1o$3KZk7X1UV$m4RN#g*MyjNVo@
zKC>*}EIEXS$MmtZYz*84oMro2SSbY9oOEP-1{l>9fb9%!1mAq6<NV|KB6!tr!<W87
zAS^!-?rSw)*lSoEB?C9<2pp!0yrOtI$U~pk0q4F19sI#>KdIb;3J%v?8fwr7x?cud
zM?%Ak$D%vj)1J#te!u#ScRWQ0@Vu0H?m78~jF?K=m||H?q`}p!geW_8qN7=N1Orbu
zsFpP_!eC5Bg#TlzzvSzqzyl1?csRnqMj1iW)1+AwBIX8E1p{2!U-`<GiqOEv8k-}A
zN`+0Zce;c`B<y-X<3^#GxDOmDe{njjTFj?#KdmVF|56%$8C?=K=mzg5eX_8KmR7VA
zjNQWvKR^eoUU8HbpE~pHskYOF9V;~+tM!^VQ#@Cu{F;?mGQ>^je|x(K6Wy)6{kwx8
zzY{3lxf>)SWQ;;iWyswhGAPaN1xtIJ`iK?n{d81<TVX^~&G>cmqnO;4zP<6vmkF+g
z-@heh=jX4~)d1;>PKgone_<V%O6%DMFVZ-lpc`NMaQ#1CDC8!3)*Hmrg7_@0k%o-M
zyRN)~Que<tMQ{=ecM8L7NPdXkc-``Nm=b*p?`_6bSVg6zElA0E*`+)9P_a%-4)?si
zKB?#J{;`vGY-RNC()YeLUk)4I$+S~6Ts}19`T_IN2QZ(G_AotL;T6zPE+=5WG!w?p
zw)v5r9hy|A*%(>ZU78!fty6Xw?&?_Ps}|i!%_a>e2RrP3wiqZY^3Lbg;azv#>2PRk
zM@;{_==7*;=TEK05w`vJ6Be+ljiiAAiKAgB9tZgHtD}RYo-0XyK|Xl5M?5K;p9+){
zb^kayCE0qi{+!E8Jh`wCwS0VCX;JI+$Ev?y%5;63CXL6JXLyA1B2`qV?;iTEuTs~2
zY3pJn4j{q#kjo+-@XF?Qgan>&rsCyIH5_y7-cf-fQwBhtzn{JDO(ErTa^&2|$<`wT
zu-z~B-F<uR-}YxzG1ct9jkd}IHJ!!Ym$lNk1%5*G*&4npug21d`O>c--)wPrE3=gs
zb{c0=EhB(o#tH><Jw#F#{r8p&`vYwoch17Vt3BQy#b>1?*kBbVF_te3K_YVZ-KB?L
zpaiIXBqhW?Jz1Tucpx_2qM>f0$-q=%{eW?uH6h^TBUq+$p`ju*-#&jrtW*d8M2BgN
z`CL|TQRU<Zbm092Yc!{yRlukMq-{Bbk6eXaSj4Fmm#u7Vb10{|<<-?jz|}Zy2R^u$
zXZzp08-8r~$=8hil0B^m)xyz;^;+p~7f&|@`Iz!pCX{6ZY>Ay%LKK-rHoM<%PopcM
z@%X^X(e$FFmPUhOs|I-JI#?4+Bo62nPIC7`5X1xr1l@3nbV+fH0f}SQZT6TjVm4|e
zVA847EbRNoQWYL7Z|=OfiIdpTyNIQGhirsB3-%M><Z>Lkn4{swRsqw@Oi>-A9D?)j
z{04(&ly;o;IWe(O;^V*J{;62}jL3wbS8d>irt3bHD=>=WGdqdZpP-d8jFd`Pdkb2#
z@4$J^s=H4?$XZn=50LwtdB%N6zTxkhytIN*ohP&w!X0clOkbo(1ierPLPDG)!I~9U
zR16H+du{E4g0+uTyjb|;VR!8^JZcZCiK;y=6TWE_XTl|__}d`|#+&E(rOKxY&SFS`
zQ3pY`@UE_<M>YlV+38RjAlu}F^3R%I{)>qd2GVPMK7(!`t&lrG@QVfOd{t*i)X)>;
zRS74zEC14PEWt)R<)B_hHn*(}$E`^@(=tooJ9ecumtZ2;e;Pl*A`KKr3LMw$UeSj$
zJWy!^uzf3W^RZ+}T0FV!)r3}x|Fyn9wbm+AEfc|p&(=FugPIGUX~Y=j(*EN7=<m0P
z9wrG6E#~>vVAGMt?%Hd?UdLKZD<wL05-eGnov@pl^xsEE*Pinr#@wxZo`MGtDGTOo
z&uztjn%<FdILUN_C-<nO{uk?Ix&+SaNV^`B`q0cV)~<B{0fE`>x7!*IjQjt*<O;?8
zdZeVt^$_(UR3#_vlOlg1jwWQE{?(wHnqBNC)XgVx4TlQ(02{6$_<>goKHIm`7d1d$
zceBsJu8+SVK_~`Kpfh&EI+u}0{>mgtI;EjeB{ebdE(W?j6=fI`7%-Xvd7MhysWcCV
zulR2-&>fkUmR1b-SwMFxO^KEqsV3^csEF6mAXB)>L+f=ZXz9l5`1h?KC+*l@^0RZm
z(ZVkax0{Nh0Iy~`{hxf|5_T%Q&a|p!E@So%Hueu;4-rmI*}P3xGRE<ghC;k8so|?1
zGpXxer97NO*@_aU0u*@Yaw9q)?t6W`IUHYLXBXz{p+J^!mVNpiGqE^-V$EM2TDDG?
zkRO5#3D`t3n9fAMm#83_oWvW{Nd<pLIoRULSsL2BotSusGs=MR@IT{Pd>N$e+8|l(
z#y6)^>N%<TH6AJoi^}jQZj#W=8xCc-f=PBjE$`%nahByFicTsRnzqPi6hZBKo0&=S
z>+;y{OS1(bOlQ_gGbQ76B;KW=i+chKYuf$s-d|{bcW&-x(~YyvFO7V%0iqS4;~lUj
zNrAQ^Cn6DidwBr)t1r(7+^j%(d@%_FXoZPvY3~*^_Z9^o)u6>V8SOxdGPVNo5w8YY
zFtbb|I(%?;x9Xo24W#&N^cvBC*Ra@v+*&D+v-(uHWe^BLGtyN?T@;Rz1iPf5BY++S
z+Rk|%JplCe1A<QPXj9rSvwpnumECa0&u86{UGhX}HwHrT(+$KK;uZT2kNvxpJd{ZI
z>ho0O0C5Z`voZ<TpSKgqIXeSDlq^Lp9?b=1T}UC;$oztetjsqa+hx-m-tFE5xl_|&
zQm#6QO>}JF$sV~8rJJ9$vNwcYlLsfq$DTcTOMI^m^zp<h9IbMH#aJwD<m2MRC~*UB
zd2TsDbU&dW1)0gDNNX!wh{q$5!^rc_s5*wZz1O_mk7#~(HxnOHxoAYL!ee6G65NWX
zad>&qe?5lP4A<xgUqRkqOYaKm@~~tv$OhZpPCjcHLDh_mfoK_d-~q9o$yJgKJ^p$3
z<&)jv+1G=7y5RL5-J$RyM5xo%N|W5r<|ab>r(}wf^5(AJG^m#K^;?zI;Ds0&I%Lg#
zb-^4=1gnf<XGl<-Elx|L(pKg1ICxREWlgBlw5pki*4<esT_lcd(CZZYY<fXe=Uu`1
zFFu*$qGLCRjHhM`9Cb0E>xj9$r|7`dy`E{Iz^^U@8GJVRd?KPi==OgaZEdY5v4Uym
zPlI+fzlm@|+JAmSg>7R`rzc=613d5^%M*u-UoD~)WOeN5K2nWBCmq8bYWC5bwFuOm
zJ5G7%B~x15S8TmfsZ_5W$w($@kQ5*(I|%15xPG;PSb-ckOCQJ-i*cxLaVgJAb_U~c
z97vR4qHzLNX`c#O8%d;TEDv#V(@UwP{3#eS<G3AQ3^I$+Z7zb={;--r%m4l|MoVb?
zyu47m2jMm4F01{jLWErq4J{nmRx?aVMonJwOz{=>ojSm7R*_x9uC~XdSt0#OQDQR;
zqzfchq!2?pCqL|lj=Fv9(KR%Td3y2!m`>Z`RTUjkfmD{3dzIFnm-vAidRHa>VT#sM
z-AHLulJmty<k(O~PrR0T=KY&Pq6$#%Y%bV4SD%m4;d!0}(LSK&4%DnUHe7pPgXq{5
zM?{lYip^U!Q%-g!@1+iMKgJ^3!CGf7?J14c1I@@<^FQeGn3`pp!y)DWVdvx@+Bhi)
z`<l$GWm=L7x7iN|>AT1D-?y$ga>YD177EQ;ECYjcE;zWf94>PC2>C;towL(Z`%(R*
z;7goAK&1mM8%KhbTaQuwX4DFs%iTZ7CD#zev2k#Zd{GqGTPoWE(h;Z<4=^IHV2nS8
zUU@p6wb#o<lB3`Xh~L#jbbN%nfSf~i>fVR)B%Pz4)h+(R0;Cpum5%zdY{9c!a3K!^
zGoq3<N4kX;(ZB2U=X>W)#Qb_~SYvSzU}8Wf2Gk`;>~j(<%~eS9TJp=)S00L*$jU>0
z&7~KgipSDJrt3LJvxN~7VdH6ONVZ=RI3;S^KIc2a231msk0-lMBw$aA!*5_=X%qB!
z#w+1^wXf*vjUA~`a&f^ZkGW1jECtONGd1cU&|m`?dze$~ds9X!bBc2J-)6Iv!?qU3
zP`4OsTu7V6#l_C<!ZabwUWW9HtkPRY*p1B|b=uBS7SW&|SU$!@zV`_9QKSldVRO9{
zv+pqXOm)PZHS>Eeh_&TGx;J_9J7KEQw#1ia8#neJ!8Y+I8R8}8*&MzIpP5iY6$zmd
zkb^;cy>2J-uP>pN&T#Q^REkrA{q}n<L6Zurzr?xZ=IwENYO6ZY!ul!138jYfu}f(j
zmNr4}a-7;y&dzGI2v7_Cg;I?zP2UDJQ)bQBD}M*but4cG{2k3r@gw;ZkDi>K+?~_V
zu#KSntU!?xP^IMCN=OgihYS0FqKa?!7`cb~5FsJ%s~Yf{Zk=O_{0C_3CZl|bh-2<Q
zAFs8Z$bQ#ruo|lg6RgPZ-vql}qZlJT`1+_CwQr3~lxmh^>4sw82Q&gbg@sfW3OXj8
zg2hB(L3h)uMjQ5c%9vJ+PxHJ~)7TMQZ8V6jKG4o(9Hyt59}wA(%x4goesxiN6XX`K
zSu(7d`esUK=_bz+pgmCaS*CxGrXa8D2Y)TIWKl8_vMqcMtO~KM-PFoj3<nNve*G0Q
zndgPyYO|m4y4Q&VfU~GjL#kapxXR6MMq-*@iw!R&AQ5zx2w3-lLSM^lx}|cBGnIrz
zE8t;Gz^OT~n2?bNa|oHC7I&xxpfOUTefr&LR2PE-K$gZ|9v5HEtfH~S>hr2o;$)pB
zDY$8*1Kt4+$?_u~YmX50Fw|E!uQW7hl4X)gK|!w@K2Nx5_r3^ujpCi%GL7v55vYF6
z?TdfVEdNw&GHM-}bc198Pz8E;R6PabZ`6cBw@2Ub$cT_R5~P-yvF6SKSyfE2U(g8s
zzFitO=`sa4uOu;u70HRpFzrow9i1ul8;t2H;!T`H@F&}+b<F81nf^Jv0e^8y6a@N1
z+Mr7lKZhM^Tn08)B5ezf;?p<=Q^qU(*_fs75fy^oohclQ>)%Dad{Q?KiIbBS2StB@
zmSWPW)&!j?XJaKrB_kqY2hemZBXji8yw1she@sOua)#W91mRm-uqE%e|2%JqB#*8#
zRwq*n3BRE&kRRQzgh_(cW<|UV_zhL1WOs3CFVZ7zOg%=Ufr|LzI}O~q#nT~I^)7&9
zH$9N016CeKF$JAi(2@Bg)yHHMgNQil{{AoB-www8NB{nP?0|N5Qp#MuU6#B$0c?+F
zHRO9;0D0SNdl!k%JwLvvW&A_x_N#Em4@{h3L;dDlomIt3EIlD$RF)>_1lRSni(eGs
zrKY!hhivlUq64m!3q0Rc)2+IR$aD?NNDDVF|A;b)koR2sKUK8qXhnGc$CEUwfhMH5
za=AI#3-iU}ne?lJgN&W8@Gn+`RaQZK(W1f<v)g4i)Y)s7Yv=7MkAcpz9Pxs}MNGs?
z+d0(rMHOwTK*M08IPbHL)WFlD)tA}{1#VL6K)j15aPzNdhbZq30o|44BxLpJ1Taty
z>c97&)O1BSthj^Wf8u`C4Gg44YlPlB21HCKQAWW?JAXcM3u{E*>Pblr7W`T46`N!l
z^h<eB|Gbr!^SuKKy7Sb6_yZ1d0jPyG?Uqr5HW@UA!~wP+7rQbtqlHR6JXg+W$#1Uy
zVS|jP2>TJvk&5+GAUNMbjl9+rMzG$-Q=hs{MgT(y39+0HMp-UrmJM*j1_B&$41N?m
zm%PkA8*?KbQc+(gGlie6HFgqze4$E*(|((thkeFZXZwh$T#urL!F{CO4WtEh@H(zO
zSorw(jD^D(&^Q{2DT>8&W-$NJ(uuonIsiI=p()LHuI{cbgWB`nq|7MZoiCcp?vZJK
zr~QU<ljWXA|7evVys@-pml8H6P^YfYKzIX}oySj0xWhkU<Kl+QHfo;Xw6P&0BVU|y
zO>B2;yjJIz=K=>=(ARR-^kvs-PomE3rtNHxF{~+Js#`-WEUdMY`Kspt3v<ueNblhv
z=5zy#q&?LT!CWfF;ElMueHp017db_hUi|C_p)>yrKi4}xEOPQcIPUFDY0TR5w%i2K
zJ~fw~Yunkm1BHKa>dYRoT|HV5fjFEVV_5tjS%UWnDS6X2G1y<O5LkC%q`k{wDBb=8
zn-6aGM<nv;XvBy>W%CF<fB@@x^r{BjB4dxCzcHJ&h!*9m-jOuDeuZ|g{U`IYpzpQb
zz~MnJr55npuLFiZ3Lg+@3b=Z>$}MR?_lnB};42-Ogw^NTTjkB04c^#z0+hM@YZm?H
z4+!XFGTp5uA=5J34YuQ5KP!LKMm*O|9GRzcrd+ENZejYW`|N*G^oN7CeGoEgeT80p
zVhC2^X}7KG7C3aXO><Sx)Aq3^A$EQUA{zfs-TltTLAcz`7C^l8GgzxPhXY=n;Hmy3
zB>3YzEv@u%*<lGO{3*m9hCRKxQ-Q%w+Ow6U$(N^vu2?|fq?xI>BQ`HcD}a5+gNsjG
zPQOy|!?WdBoE;h8=iZI$T^o1U`lSChfU?ws8i$sBl<3mFlag>1NE~eteLYf5K845v
znH0YZQPg>efLWomvKv~k-nME}WIFW}2H*2R3Cg@EyEjoTNwipAGV`T4h)05)BR;+8
ze9sc|GG{cgh?xdTFFlM&@!MJ@oC&W$si>Slv=UkPZ^{a_N&dAibHSQy09`7(wZjPR
zqY@EWe*~!ARixwgk=T;5>)E_y@y6CQ-#24^yi^Yj4aEX(Y=b*4_pm6#>Q9X1!;vWb
z&v+NDZF08j`S$j$Cn`!gLU62LjHhSgY)PBHgba2}pnQ(qfa7a;{@}yHJ%1>6#mEtM
z(^I~}!ht%P)8!@)DpsBd?k@~m;1QOVO(l6GBI0Ah#o@__hn_!iqyrF-bq0_j%b-$v
zY?%gafu{X=$iW*k=v#|aA{7m+o+_#wZ7phLzq=AGm!<&PpmJKkQG-=pQ3IN}Y}~*~
zP4__VCq{u#H^-dUKJuxVCDx<2tKq_3W?D<?SIVqqQ2tKA)-B&>U87;$&kaU#e}VJ~
z8CFf~Tk&xV!TvhcpL|fs(rt^E>$HpB0+?91QN!1B^h{M26^6s}32>ZX47t}H3b8zK
zkUpo)WW=+5(j4_2ucA*0`CD#m8Io|PJBhFtpistL_3sMMq%T1u<<bxdBATyGz68xR
z54kZJNEV>iM*OEhk|F*}B{J?$7KTu0Oq_$1l^48VD_A^NRiRv3MlWw}k{fGxl;vpo
zN|)$AdCBMPLx{wGy5x*KRLlA4Tz`1~C-=sP3ZB<;w@qAJarQ=%#zgLAQKPMdU^D?H
z?Parkv^IL(L=4>8TY#EoNufx=^Q$)61`9$8V_?jqh8b|Tqy2LG87}J_o1@fvVr*Ze
zAOZw;d*bB(tRKIG+=c{<bYoCCwyuEqzVC6syNcFD@&-0*{qSeq={O7dE7_040AetB
zce6-bCpD&bJq^5b0dacA$)|c@xB0c$=F7#?-4N27x}JMr5w*t3@+0vI#L|XCo?43J
zYP?wQMn|hefYvY<U8Rqnn_my_7#9VF!*9o;*9z<O>yZ(Li**$lN-1G8A9$bUyfE6@
zjc*NfcLojDH-tw-ru=IB5-2wORR1$jyFQqvHiO&hQ}K9aV0*iaCZbrY^@O9(+vSA$
z%YPA-m-_mKedRFaxtX8P<t@sJ&aL?C)MEboYaupRs!2`L{}0tw&-sT!fCtK)lk0O@
zDn`j-_8_KS0zPrw{fcMuTrMx=A!K0OLEp4qFOQdSpo<PTL&SY#1E5$w!!ujK-1Hmb
zfw(zD;LYnfrMr*62rz#XFbY`uN+RF_JFvZ&g^r<Qh0`bye8`A@f@I$FNnRl8CS^T0
zIl!TZshSPV?~43A7T|sFtQh-4TV?44sG-%@PhW0I8uv#E@<w|9Lc)&(Qwy4SEk1jj
ze){^reHlEqAFg&q!*_U_h>0IVmSKU3t!W3?&peRQw<LfP^6<BO;p?ZnHOv4eR&2C2
zi!wwRU0TxYcotKn{-OCM2q^?GCT}Z|*^CSygJ3_f!Bs2_r*>*nFo{|a>$|^CD>R6;
zq;<|P$3D~>8XArs75Ns8a$MVp4rm6S!~lNWdF#;+!GwVZ-$Rv$@%+8ER3Ct)pSbN(
z3>-g`Un>Q;I`@1Ysl9{&GRI2ve)!vu7ZFBI@1vqrG0t2`n!2<0YZX5O2D0Z>rOSu;
z+Ov%b|Emd|x5@YWzLQ7zqoXn>qnoq)uBRf5&H-Ge`OO2-_klmh?SdLc{!2))3fYH<
z57u=uTSxDNk$BbUId~yr&F~w~aR)VC#)#%W$M(;*L<T9(e~yifY4}|w=Fn?*E)c?M
zBaLcnYvp&flcBMomGT?+ZKgza@tJ!dS#@G5K3vuFLecqsZG<U@S7M=f#4m~BYPfOI
zlSr_ES3q@|d=&9GBhkQ>153E`7s&U$!94%q5=F3EsMab)R#@emoLeNI9DL6;n-jeH
z(eZo>)w$JXN9N;O*d1r_yVOdO=jUgMhzt;2+0UOp>jBq^qMJb0Hy{feTZbI>X?O3t
zS0*1A8VwB%)ofxRQ&!apBXO!v)W6`P!2pH9PetrC?Qe6`xO}(ww-~K{@`@a^+KRbB
z9MG+<1`5#zYCJDM9sdGQ<F3JLlqU)<7SG)q@8p0HCg|qIwWt8-+v4DbP(t)0j}*@r
z%WuN5bDF=}*=dNr-psV|j+X1JS~vhUY;A*Nc%<RV&)O-j77=>R?VJBBpak^lcQJ+S
zzaQ&)%S&z9vvdXgN7HW=rR`wNR`gc*xR~&Lr#AjZFaybMq11f=is`@3HNVPzLKYAy
z60_e8dP+q`l>f-Q+8<P1^6yZ404Rz*I2bfZ1V@<N?_yR~R_o4I8c7c(i{64e7PqjR
z?(BeP_s5&cQhDlO*gsV@;P_+Jnh*i#016l(a179=D=irM&5ouN61pwUCf|PuF34S3
zN-Dr_iD?%TOm;^cPUz}{S#+)}Fs0K>ZXo?i5JI(t`OB(<7myOzF<O*->&9^S4d|eo
z#Ijo!Cl^)yK-yo6jDS_<+1}pq#QunX4O!`qE0X|{2>+Y@tPt%9m=l-%Zwkn(G`-9$
z3W|4keJ-E(q4><FGhc`=v$n~w*u#?0fp6FfF_0rjF_qO<TgU_0brt;s;!D6I@4SX^
z6T634!Q5R6<Z#$QFdB;7eb`j_RV>yxX^#q1Q4<lm`2(zlO$w{kDXKa{261&9)3s2a
zIK(8E$$o!grL3&XRHZs$j5Pfun$h>0nM>}%QCq9(bi&PMRm;ZjdQ0F){SEtne`Cz5
zCR`ZNeGV=>vJR|`qw7ak>ODE8Zwi;?*u0YAb{w^U0*(#i-aYJB`}6ZNPAr*lq;wRX
zp*H5z3^wp=9XMO-KuC#^l`?n7jO;C{H<0qBpn=g%iF#9hmf~_Ds-0G!dEkc9&nF!6
zYTtTlxVlywMo5KePcozyp^tFVaR1`Isc!ZVREoSS!As|j4h@J1S~SDum=HzZA15xO
zj9;L^V6cKL1BaPu%Zl6M<D=?$I@iJ2)_6HRn6h2(m~(dl$;Q0g39;1CVN4x)DEZ-2
z|393qQsM?6ty9Y2foNbjBO&5tF$DdA1ZtO%@;D2oG2=Vr1fh}q5&?)ywcwy%2FjYS
zSw?@*za)L8Q7Nwc4>LPGxwkg6sFMg&P}ATzNM=L&0|KK26)$VPB>mFr7TUB}vAmR-
z*+-w(u0SN@GVtX26=2|y7=r$cL=!67pJwg@RIO|v`frp2ZZp=vb8Q?-y>kkC$s@Q+
zdp|8XGOVGXppSy~lTez4m6gEZ(vhnz;7D%;Sh*tWRMk-97PAWr88*z=_oUqf8J>b$
z5ZM@_J<W=_-iy1sIw0?hGSq%!ZmtObp4Y+CyJe*c&pa1gdM8uB5ucQ_+uqm-I#mJt
zx0m`VDMj;ga!xDO0BT|7?XFT}C$?%gLno&i)?b~i@8tszf)?JLM&y|H8yJnM%F1q7
z{=TJmKmnAA`%{4K#8#V9-O=GabhmAE9upheRVoajf}E&9Y{+el*&Nttd1X>ZxGkP{
zcP&zTO<GHZZ-ujh^OiL>X7~}E*d%Di=i(s@fpp_dl8(lPhE@Eohm+dF+mXHwBmjf6
ze?V;3)Z^kx)RMghVKh_&#X{`l))QDbUBS!_4zE0{@LWXEN=Ui(m90}39wXA`oM~ti
z^kLUlea6OUwWO!llCS!Hw2ETTi~VCXEIM$z=;wvym5tF8ZGXRRpGagk{(2icN&94j
zox-e}FBirDfI;{&o7YQ;(VPd;TwMA>(L_H?u!Z|KJ1sXJoztmi`y{>HjdD#~1gL9i
zxjmoz-3w~FJ^&Echeg2aWn8=fD8}B`sCw*XZ;oa*o`G}$FhVE(`Wp}|;MUkmcN5y;
ze={Z9-R$#tC5k%d_a~OLThw{8N2hNE#kp}ewfki+FK;=HnD^}BzWe>PD76`o%lV}+
z^k^D-J_At$_c`-5#_z^AdZ!vyAalYk$US7`o~tf~JhTP>zTrq!^wo7r4N^A!Zv1|0
zd|<R}qzy$-{x6h3hx#m4qi=;=*y|<?@Yak^gxab)*br|4Khi*#3Tb&KsERP(7g7W<
z_PHF8++JlSEEm2-0z_#46Hg%7Gy%*ijz`$KU!E`S%!06JmhVyLvd1~HP863_aqe48
zwYXc&exz?((FSVd+lG^)8aU#^OfdPrsq3;bqEcCZK!&buTvduhsjq{9`;1D@^fM`~
z{}T*!Tz%ofUeDoPz+O?VYwbetD@0*a8{Sm2k=E+<*G3XJ31XE@5So!Q6EU5jKAI(n
zZ<OQFvlq=bzw07H!AnUgend|bD%_7Y`nU@~p5%Bri+E+&gHOO{t4gl$1t&5-)&S?{
z8EDM=vAzQj?en(-ZoByx)dy?D!WSUP@h6ix)Z?rFLzw>;aauK4HF!JKW5v{FjP6k2
zFOdD^_JBXKlc?=%=}fAf(<dT_;3oXs&b{e7z#IxgC=NXbEp^nlQe)6|<smhI<dl<^
z_QkF3?qg<fQ;B=3-Fp$6?-3v;$@sm3Vt<+XH<9j~tlU>qQ*)#U^4I3h1#-j(gggL0
z?;R32t{Ht!grEQMv<PzK)n?!=a93GbnFypp2pLs(_Q<>`u0+}8s~Xt#Da^FxE2Uwp
ztC_|TeE6rPCP<7<g=^{erP-7fi$k6+1y#0`+<)}ogszq1qCo#(`IUi-NwMCL0mYlU
z=gw<eVTBYGb4Ds0#2;wjBA{XB8C0DG<Vr}Qf?!y!15H3N$}tZsivE2I-FI%%!>SRc
z7?=8Yme$tY0Jw7~bYh3>;W9z_T(%Aa)}&9|{_y2KL20!phh~#+6@t`bB=F<o3kNm?
zVdhH_&81@MfIOKK^>RsJVUp1kS)e@O7YrS5=-l8YRRskB!GHe{8vF%V7z;Cg|86Vz
z2$tr+nm;e7t;HnGA_as%1hYZuAl5)VYzQ5CRi%;G(h?B5!c|Li!K8urTYUR=am@%#
zc&jg9r=mz;vKwg=J2@yeogO7JbMY3z5T~$Q%oQ_gjx*OtJPvrjJAd8^#t<o0!vzjh
za{_^28;ZmO_hlAd2?Su!Ey4oUtuQK|rv-m!v{IKy`1>@h(-q|ZRN_xWfA$2rK!Ghn
ztyaOv(hkea%!JxxvfDwIhIy#%xl`D@QD_WidWG1Ee_LdZ5ofj8$EMKO7HAL>A+PWp
z&ESozVM#9+o2co!W5i=Ks%*_<;HaEhUbcPw{|eV&OT#3B>`CG=^v9+@d+bdAChv}*
z9-3?vtv|-9+LwuVNds#@3&|a_8qz0=PQ}A|2b0bP1+&B*&6%DwP(<UMPicT6Mxqig
z_~EdVXw$1`6tcIB)k7-kC$xgw($a!)5uN<tEUp=nkbn(DCI&yQ%;wBaI6xdU2?F1r
zYTng%Uy=yM<&*UczL|$RmEH^vN%Q5>1XKXGIfYeFfFcR%wictrB=7@GW<QN<46zLz
zn2|T^1)F1osTsU8e*Eaw?vhd^a6Cw}gDN7&doddELruA)xlmm)(6tGqM^S)U4#PO^
zo1N8^l9By=p4i&jXr^YM9__HwycLK*Mo=53EfH~&If^ilHb-iNn%{pR+v*ZjP{YK-
zO4FcygbQ5hOal~0)c>b-K}JMfteO+c=Knat-0Jj+5CIO?A~ho|X=rKW>dK}31Id(c
zJ6Tc4h{K7V*tuFx(dhPKoq2jH;6<u$Ovhfpn{~1Pi8taiDp4P?cg_2Vygah`54K+J
z#0%5u1J$HjP+eW!zWZse#w<CTV5wGW&~>Dyj|LDZNJL=4wkjBi(Caq?uw(d|DUPY&
zAmME}tC;cMOIHodtEwdHTcajMc6c7G^&L7W*?s&yjo1LyZgj~YpG9p0xDnW4Y=6?2
zS^~oE(u&2dOlRY6MC8L>_x=5^^O}DC6Ce|#Iu~pU>@D1_vsz003nPTyT!!2&zP$L1
z3t{J|M?_Ka@T5eIk@?<yp7$$?UM|9NF%Va9K^`6+UNq85!5~(N_ioE?8aY}uLQ{KX
z=d_eem%+3QJS3W>OB$n5)PvhK^2V&m(8Qgdo>|;dX*Q!xZ4iCA#CSOK=o--^0`Rc4
zTdo34MMXszO6i=II;~b^*nOzZROSeua2-0cBH#Z>fDi*#W@ZxarWM)HhC~>^V9YNg
z<KwhjW-qq`-4afdl2t_im2X~CQZhhgtz~6?$Kj1WNpWr0HV?B~+BeZ%t{9s)g51a3
z6M^L;Qk4cY>KOyDb?{-o+Uy0;DgkvJ-P@-NS{xXBAbe{$Fq<paigZoGCKqULZ&w0H
zo2MuBTnW=uRIttkY!=QD!T-BREBcdzTU!9oA2m9ekX*ej0A?lmFga!JI{!5(C8hrQ
z1IwIojljTdd#W#ivsaM=+5ik0>L;9sd}h8tL+G}o2+i%|U|P6FMu22?8dcaQ_qh8g
zDjZj)QF7%5JUoH%k7={aJt}DRE&FScEKoz>K?W}Si>+WPHU=gRSKuoDuSv?<^$Kz7
zJGqo7dEcC7w_GhHhyfu4V(S^b)hZ5=H#?u|iCxVR3HmJhBJ(y=07<>y${s39N@RcF
zbc9l{a!p|aqgf!sNrctDu&c_clup&-<+=O419<!PheZwz$=!#d5&L<T_5Hx^BThZu
zWE9Q^)(B`*k2$5fNHLXB*fk_qX*Uv=sn%+Y==8fk1{*O(^Cu<EkliE;S9kaP;^NRM
z|1c_%O7Eqnpv5idiC{R(-(?$!rwPZf;GfB@?IP6`Rg$&}jH<b(?h)l;0;95Vq<bHS
z1kYL}^BC#DV?djCOSi>wZ35UErUAso!HOzY3UL4r0SyFf4c~aq9?|z}(H$VZ*kDXW
z>ogcoH{xAxxa>iR!y3%+EVwGIt;6Zkig&VB0W|>ZkeZwCOC&*Jte^3QM#X^dzy*_g
z3%ECZsda|B&l)*0Yrs10ILP)#-x-YQ+x?rE91Fk|GO#v**<7b%iTn{3U?YJ7wNzC(
ztO5wHIJ#`lpujZjREz|W_siv<%L?Py$f%M}L}Lgdl8QsHp%G#FT3Q1X9(>WCs_BTm
zh0`}GY&`hqLVHD2mt;5zegsxa=(f5{S^!vRWWb}f|CT=oeXN-8D|CIz^{_M}x^tp}
zL{rVv?=<lOtbNFOD|jby`~FM8&Ct+)1m_<J34xC@1-vQfm7AKHkb7F60+Dl`R}Y+b
zhp=|{_c-N<nGt<}dwji#Xj|rIj>$Q^Ohc3}zsPERgf+wLw7>+%-?S@|Y3AAi{1;R8
z7a3!bV?ey{J1IV`2hMxe_=cjayJg)EB~IvNC^wN6sEN$0jxEKNmG(uR&5WHKE?f2Y
zXqvRdV^|7BRsXX~74c$#WnC#+BZ8Rpx``kP!ad;6QW@VxM+Ql!Cd9D)4J|4u!BDVi
z)fV&QH(arsYw0A)^={hWnr*IbRITTS1%E43iws~@Mo;RA$Dva{`a;z5K_(ar(BeGD
zufMNsyoHu&6a%?9y2#}Jj;#C(uT>bWT)ocTs{eO#WF#c0D~v!C4D{n;&Vkc+C^slz
zDVL|qh+Hx9b4sch($SIMm-64v7Wy@?DmCyIev7{C*k5SHWVE|ocv3BDlL&;qs%xnm
z1f@4v*Y~CWdXgZ#*m&JIzZfxoNhn$ZcA)~L{w)ze><8|Btf!{?=%KYiTma$G3>LUh
zkh6Xzd?4O<fXC0on&9DKbyw?=9r+`rMNd!P^LTxrtF`4aa<Q;Y?_M-v6rs&-FkrDD
zk=KfiNvF&G6La#aLp^}U^;63ys$$kq9Yi^SQSys#?^CwD4HLpq=l<u<$XenNOrdFM
z2>(>#(>PSb!VWPuS0{)4H}L;kAhwOP0FZKGdVbM&2XWo{8lOF;hjEXtKCQFL7~&U-
z9-2uRiqzKe!XJw1!xdT-1gy^d2E`aU1!d2se0^IE^cjk-=)?O7R@JRC$x#mR5i@P&
z-@>DkEfz>r5bi0J5u2ShVx>{=19#s)lm}s_qSP!@*x1?*t0*h8;O-=89R2taalE~Q
zvb*p%9cSWyi-o(ZYcy@$ga7M-KR`G7IjylkP#E=mSP;jl6^QH)U%)tt?cyUL<mK(%
zc4)u;>wD^0HQGQO+WX2a0Xyog;X?V4Grvu}9fKP2@w3fuX@w87PExvR^=<eFpK&82
zBfkiYVzQ$iBIA(Xw{$<VaB_0RC#M&=CSgm;=<8=Z9+l*bYgKy5@*Iz#SY7WLR-s!c
z{Y<R+e+#Cf{}wK=79cQHEH>KUpj=>R$;sru6v)I#n3__qyiT9|P?K%N%k|=hgy9JJ
z6EMP9Qv9`ytKS4Z0P-X&`Zg2JZHTtX*N@VPpyLj}vLOUWe;+QpUmqkpju<%VO;3)*
z{5=FkS0pBk;-XyD*`6|2Y{Di^0%<ry{V*+_8HHt~a7=>!5)EK@Z7_>So>y=W$NSGH
zNjY?WwxqkS%v(6xvHB44tx!z@SbH*{)$s7}J3uaQS>Fb%wuFQPKA1Pv_ZwAgEmKS}
zaT57_c1%ou?>lCgEdYa#VOi@;!%q12IAUpCBTc!bcYmM&sSZI<nkdv1PedBtS1(ov
zY9MA|46$j92^pU<^zJuBb@zV_P|qtxRYpbzUUnZc-u4xuLRrPvo|Ebnfj18)Yn0%n
z0RLTDJNSlVs2Uo^6uzABXk{rN*(!fK0Sh-LXfa8NI+jSam}wn2Aw(2oQ-;%t)A=s;
z$-5Z4vm2heT9U|s_8~E>^WR_};JK@SVQ9VTGQ#2sJT{##HpPpnQ1Oxs3%Z+{o9lT1
z)!nxmBq^haZ09D>w^q(}Dy&qPb=c{z>S8#E>Zoe;DC%naclM9E%m$6|bWr`e#c%od
z8{ZE|D-9b`=(Lf^Jv@I~o=aMPb2tQN2ijRD-mFf28Pi>g6Iewj7DfERtBHs9$ZzNR
zGTr}qhxuF^@>u3stw6}tMD6<$o&V6tF&D|-dmFZKFh}Zj(8e}pmru95+I~q>r1S4U
zhBBZDr5o}~;cRVd`<K)Da!w(FsAd!4dy_WBd_6lk+4Iy&?#}S8;Im*?#Asm0^POHY
z62tr>xJlXrb{g1ha9;}>DT3Qny>D*s^C~M*HA<8%H&r)No<eA$-_N_>$=|L;-x8Zb
zlUs-7ga3r2{N!w$*UsJZX}c*E9toJAy5G`CqcX$En<I?R<c?@4hc@|5lt^Jj$I%&3
z3h(l@QGh@x;a!4#ldcvvZUw1k<nQwVn4eGo)O~5|^gPh;6kk}-Uif8oX1)I=^zDpi
z%I^XfLtiz_NC;0er%er3+O$#Xt|%tM&uaF+^bi~9i`Z;|cj{ODswqa2JiG9!iMQwO
z2>A&DFJb>Rs+#^HpxN&w4b)}K9?0?Wu;=v{FBovzGA*Ys5bEmc+V4CA7Z!A{U_Z4n
zeLX!oK`rQJ>LaNab<WsU1IqcPX@qK;YS^F}SiLYsv~Ano=3gv~(^PtBmfs?tUu;U4
z)p92PV_+3Q|0h<0oRA(?0FR4bSHnyX%L`q_YPj%7`N)}U{2|Nr2D8Zr1!wk9KPwao
z)r=Gg#;`C!@L-1YaCxGTw0_rq>Np8|7x;Xf>3;8{$)gzFw+C3hvvXTXCs{60`WdCT
z<|js|)rq^7d9Ab;qkHLKTz;o4CZYN?vMX<|f+cY{^@5VU%pvRmkJIRoKmFi&CY{O6
z&-y<FJr*|n9(}u@PSDN-vtKUbl8yeYb42GX6>Ci+BQnSCSNEdSYA!@qVW4@i*zGSm
z3=mN#+}KTIbytD=Qe#syhnDI7X!-)06dMA1jg(uf5%Id++CiS!b(1YfgC~_1W%eA_
zMHJ#blhj624z2vN)L70^+=zRz@jDLSrJ6t{L)HrHMHp7?jBEJ*{Mqe^o$bIFEkIe0
zd;|l!iZhKy#LmEl*4o5rP_2S{w4>-x(bVGNmy5)l7mFp2uD4yHR`1}LWN9v<igBfy
z8a`pgfENa%I6Ke}Zv*s(!wQ<4_>F?--G`+Sbd|J*)6K%~6&pI7N$NKqEp#v2QBiRZ
z|2QAdT~4pt2vSg=y<~u;K+&UR<{6wa@qS7E{v#O|(Ij5x$iyUuGuC`CMjXJhty#dA
zA}>G_vB{#e&PSg#O@6FifSlT*F;=G>i|HCLE*HF|h_97!%c)cWce-F*=w{6uf}cZI
z!@u8OCf+alPi6@ErN`D@iBuq-aHPuIl76vYp$lloWrh#`5^$U1C2-PF=>DQ5>ZRlU
zxSg;vJzYPc^s~jb=EbPze5QFeJL`*1N~&+y?(DCh+c^BNJ`p;M{>2SPK6t{h-S^wp
zM;m{26NgJ!+TEUKrB6Jf@pE-bc-uuB76{u?UY}0vJVrL%pAuF!^dBdA{VP^UlYy!L
zW3W{2!A=2OpivmfydSp0{&AZ=axj1=Elr1;r?3StKgw$XQ6)bDm*+}}eF&ODF#4i8
z^)3Vn=sWQ!e1$X3`FHJEZ@J5uef0MFOPzoQteTEaSmVv7uJOa(LCm>>i{ClMJsKN+
zk^G}Mp%i4t5f1)+mkw-sM+TR<3(CifHfekwH1)-!eQAU!SUGn`3`2?v3QzAVf;fDF
z<(!b5^%mFZHP<^~Q$<9(BpOT(KX!Tw#E;N2BC?dRT#@XIwu9mWNQ}n_eWg_4R5|&h
zC8&{7uo0ZdIGA!@aPayPe9wK2yRS37b24V=4m9T=XUx9WU5|6;>#O=DDH?7aZ@07G
z)?3_`>Ma{8%FFM{tKqsKg}Q$#dtHye>%76{+`77@*n3*u%Bz7l46bMYo@D#ln`*4x
zp*}i!pClJ>R6RVhEF`Ds@W8mL8n{l?>}UC%1wReuaV$JHfEVT?jJvOPOO8G4f0|X-
zH0)Qu4(Xgdg`+Me#`A#!Dgtxy%M1E1;KXi^D{6Rfi`*g0MT43#m*Ziw#{rmyUC_G#
zteux*62kUH0lB%a^R%}arnUDObpZQ#FRy%`6W4H{6q$=4?$0rX|3k2V)forBgS-UU
z(wzUVi2%rmzpklJse4kAR_V?<IPho7=Gt)@-1+C^IdhCP6iHK4V+RKaal`=|fDPb<
zQZ=d1yGt&4f2h{EZM^%t@vbbZ-|&||VnK_^?-5EVM0&vRiFSJm=hG?Kdn}3{SF!u{
zyupd$L$cHR3xXfg5H~NzOso&2{k(?HPE!lQ+Qz6LM*`}B933&p@M}KY`2^=v!{Zaw
zddz9*lv$3X5XRr`4eptg9dQ*`q%L&XYZ_>t4L6fGHm}dw+k@njmr5;Z%A8ZG7)hI0
z)WG1G&@N%kZ~GrR`k88e<*SJ7S$sR2Di5ec7VSFubKE$i!gWxp|M7bv{M}BI)_Yan
zog-Syd&uq+OqZ-o(9$0kwe!~9^CWm?)U*Uq^<h-6v6=24$3UP6Z8&MLF1$Tb+WKQ)
z_qzz$h~%2@Rvp6n^GlB3Hz+Q|&1-H|As_VOoV6Pd(KHe3w{o0~+qZXtH_~%olj+m%
zY%#kc{arvHWNP=*q~XQ`w5a4@gzDPeW?LKL6*e{%ymO1whTm)q?>c>vR~SDC1<0^%
z)9dtVBHZLM{r%r0T4-AvXtmm~Lp#gsxQwtuA|c8P@nZwac6^K;2{*=_V1~Gb{5_?k
zw~s^KKDG<S0Mu6ic%fbM>m~9hmq+YpaJm3$^3CQz=iAc>!UxZ~ia#+)VmtwKDeuNy
zkky+fqYb-w^^$ClBCqES11oh`c~n$i*63;f_mj{HO|~Sx2Tu;er??h_mZPSFIRCS5
z|5p*Ei*uK*Teg~?aYqXq`d%84!gMDx|9!Y_e#b3u@&G5Djp*n!a;6U_@AnYZcP34H
zzv79e_m_)QKTkLL$5K50K5A-oicN*nJ{2}*%>{#RF<!unQ`vF#3c1@B*3DsfmcbVC
zv*~z@cSBQ_?7M|oE(vqEjIZd2?lb2wRq=6npS=Cw#<2^MWAy>PA^7;bI<-un?s<s0
ziF0av%!<5#GBx+S@&4ACI}a%cM)R!mtr2RH05)Qk?HCRQBzdRF_LSOf*c-1xW84sx
zM)?hsv?tAF7my?f`2S7qZnqoB;DTzOc)x$em)L`xoUrr=J-lGtznqkC^p<$<%3HtL
ztP>uHAS%L;U6V&Y-wvXvX5RIX8b2a~Qgf1%v>Ln4$sP5csz<8Zlw*JW*DnrgwY0R1
z0XoIJFs{_0qCf|(TI6|YqMXfV3#C}oX{bD4!c@x>GPf{F?|~}Px0#z)I8THw=f1_s
z5I#7@rD+nY2;PS#nllh;7fk}pB}l!BY(@2qxx<9B_BU8Y{#P?O1a2N@nQcGRylX*h
zk;FoeD>>z&ZwC(EXar2mtQ_;faObb#KfRavX}MFRd=9_mdyHrDGu@ns=n&`4X1fiz
zwV2pClvjK|x<r`peVgcR12x0#t_=u5SYpgC2x(us&0Lk&GBw8aIDF4ma<ajrD>*V`
zMyN)D6x~H<)!WwOo#)#d@4NarePV*of~ff&+t(Y<2=a-vlweFKM`h(P_+7{3MP8^q
zOh&>;n_m~(D70AJ$M?aAmB@2*bGB>kZp9ChNpxO(oMf%<<dG~N9Wx}1HuHXaknAp>
zgPB3!JvHOrL^Nj&7IEUq?^|(Vxt^6f;D6l%uB;BdJGK#}J>eD%!}z^-NnWgHOy=3)
zjhC<|NZgw=_vxb0reNWfz%`72jf&qrZUE(Da3YKA{Cu;aH>By{{QMT$K$YL)axD!M
z>u>m4!nL*JyLGvDKm{Q<fI$?!9%5r1uo!Q6dFcXcpd0hvmf~b*@Bq8qMmFo=G>J;p
zv%22vRHQ6!bz>p*{RxE$-z1kr;mqBm8AC0oc*1vu>%jPRuZFDU;$_c;M_!J^B7mum
zT);S(@g=tP2fH?$>O8U-Ows@$mvt$Awtw#z+*pC*QYhOUlPJN54~u!_b-_!q_V>Ll
z!oh(C`2D#lFz!%ZVZTA2ZU**QGUgU9&0`jbd!k+k+u-6JI^W%Do+fe0hYK67d&?nJ
zcfRK^+ol01x2a)%#Q@-g$#!9180M9Gm!Rp+-|)@GZTH1vm^|&r+kIVWtKB$*wP?^$
z{mDB-Ly)&qWW~bLbAL+O-}i3fe3F+t(P4A7YpaQh1Ir6*FIfwXD^B=U9`)>Z0B;w%
z48);&g#-O0^ws2+{QcxrEqU!by69H)pNY1sr;NBc6DEcpV9TrbIDGw@_RHtd#qI6!
zfEezx*+#!ST~?vU%N9n4#q-U7?NEmxALT58IS{J}?D}6{T}{f2$9r5K%MRbAWp1B<
z=(jKjsL1`icrN?{JowC*YLcqqkzp-6eY@g!;MHqfmd<5e?!oLMJBXKvRvDVKmIpf5
zx69G?cpt%Tx@<bQBWVbdaJ%A9t+@AlVWQQk>YtR{IQ{T%26c^s$NUfnbb_-G`gmfp
zIG^2=P}tg^!X89jhVxIWMCjIIgK#p8yw6}YksDSTxp_6KbRQ=>ICKw;{m1%`PAUdf
z)}!~dVzL_H_CjSBqBp9$PZ#`Qp4vME6qkRVRJ7FiLx%R-Av-O<y7me7YuyTbT-`cF
z-p}~26I5TG<tAPzDE|*lZ{gPj_x=xWjD`Wy9R|`Vp)^QHC^3*`fOLa^ATe4A5hX>W
zVT>9z8b%`xk{hK+w{$<dKi}W8|6s43UFTfy^wI#}qV`>eZ4>2+=mkw5!kQ^Tx1)(c
ze;;ghEXl)Bu2|}w?H_yWAk@jpNm2a1S09@Lh8x%tO!7^|!b5WF&@;@Rnl3%q<tocZ
zLU(m1<+YXG!MwkpuYDP*udnac2*;vROM|p9NrPk#=FUH5{&SYKh*9(>l)dlWS$hHd
zO^?5LL|@Kq+wKk}f=vF_P{JK^?_b{=#(bRE;cwg3-c@f)z!AHwF<>TP%gaF0`q}TS
z{VQL!^tq}4v1&1BIEUX#>1Y=6{kEBS&VgzBg{+aO$|p=m8Ot;g<bG!8G*L*v@lS_x
z7)HP$A+nnoX#Vkrp<m|m#3RV!2G<r)&h&RhaHaI_<n#oQQDcvAc&$(>=|1l`SqE3&
zoRh_H#H(_;-%0~segXNzA4SICb;8VH4E!Oh-aE5xD&<$(&m^u6=3trRvmUbzN;k`=
z9PsUmR-s=UlCw>Bl&Zwx!F_!<dlw1|m3tR!k8@}3<W=mdD1#4)oCogp{p6tfs0~TT
zY+<5V{+jLUTbtq$e6;%1Y{^`PK~unL8|9WBUESq1I5aA}QJy8XoxmHzan>0h@K{0O
zEV+gwto^kBG4492_3TSvsdwL;C{&Y3o;~yW^YJmlzjfPUD{PfAN4wgeU6GzWy9<E~
zII{n02#gr{(mCUq`jZVe3bPcPbxpqn)I<fL>8Iw+qs@1)EFLY^BfM`;a{5>*-+l3!
zZ&{gaUOIBm-^2Vc_pb(~IG5ir6QNJNHe6lw6s|5GPa06(2pq8?;w-!u{3lD+LyT`7
zce=*bm9FY$EZ?I-f_)11$##f%IK!OKOA&2t*K3z-E6n~LnPU^kQdDz(Yguz?7n}@d
zFWNoW?+k$nP#Q;nr=zBRir1j3s=BLT_oynH;<<J1<@~z5L+mqLX}eAWyEsOMql}cN
zWqfuFZW(f6cVs*#nD-gXqXvGal?R~YUg>~}J?j>HJiskFtK@uI4e;G?Sc@Aj1fXqU
z4~kHyk`f5$By8W>`uyi;h|Pfd0|xP&v>WR)o#ZB$(7gz=*BuMzTQyrTRxR4Qv*$BI
z>&01j_fEpL+sgTRS-C?+PQ8+olaD!djD_|ehzZBbyLL)yd*kABDY(!nvv)wxo4=10
zN-A!S>kwrvL)k1+ZiYD9@;96lBq7Y2r;Q8F;u<n9Ev=1LG&dsi9dQUXNaz{nNTGJ=
zHlO{K^U<fQ31Mo8dy$IT_P$a4CDq_QGh(sz<E}+Lcr&~0&03eNIYrJ=@!BPN`euXx
zT6Xv9EW~QTAA5o*F8vi$0emiaTa2CZB3s(ty-G6IG*-raY!pCyYr~m|Df+EfQaO=X
z@An$FaQ`lYSGTJ#3?@7L52M44L=l~=X){)#3xD}koebrbUzuL|iJ)Mv*Uj>GyHG(w
zmAPBjGcKp34@vlqvzD@t&;j8<+jq($_Q#Ajs#`&^eBNO<krLK80%%KJ;WFvj^+DIv
zxH^ZMw|JNE2*i)8U&qEy@olXnqWNysd8N^A=;^BKNmAvll|+;Mb<TA&bp%=RR_n!D
z=5|H<?WOoJ_}Fyw9tp|E@3=oLh~{86uZc;FpHoUmahgGQj9cf&o8-Fs#Xv1KpCM5d
z(|yk_OdH>W7Gdm8rC8V1Q8dXbpeHCY^AWt3o6bV1ZEJhiU_ovnNs3`Dx<r8h&GR?`
z#cx!mn|L?6f^gPO`S!%=OO*g;K2a*z6ID(&AN??=`Tbz#*6FB40je@oVyYrXxAkn_
z9pVtWA<k{447s%lTlh^GymN%xFA*oD$su2HNuh%1LZX?obaR`fUL5i^mGauMr0pil
zBeSo+ZN32_;xPQfuB8E6@9~-jr*##fa^|7yuNEw4DTeiy<VE}}`25yl&Q;y<HrG_{
z^flwQl8K3CNqL2S%oJ-8De2jp2v{q@*GjgwzJ#w#kQtAl^fkHDy4F@52??p9w$g0_
zoD@!9xI9=-uKLeC3B7Fp8V3&d5ryx~21VMUAg=KrOgzYIs-3oziLYA<x0_;9m<Ft?
z)*PJg#DA&LYWUgdB*d%z?b2i5bVOD1!G{(RTKdze>FKsyt4B8}k&(~cfkHJr8m#Gx
zhcP(jrW2Bks3<ud0lkB>S~#Kc2sq(mjh{2Sxj*Aa#{5Yd_Tw~{^kl0ao_q6=(P==i
zoCx-U2X2cv<tfQg`A(J_PPfAXZ$$Fpvc$jHP#Rl0I23Pf?C4rpWFg?vCk}ZH=~B%l
zEEVC`viXFzQ09^LlkJ((^&js?0H-*5cnTNFJJg6nYF!P|BUAqD1T~G`{7&0i+&9k;
zY%&PJGWC5glMnnQtc}9Qa4WZ2Skcu*lq4T$d^%j|s~0juxuT9Eao=bJSkWB@26W(p
zii+iNazw<ZQ;Ph*mqKGOK)m}>ol6>!Tvm+T`JtYzN=}BLG(`^)E5UM?UfUUz0(O6g
zUt&r^tt1Kz1pL%*mWMy0!u&7;xP`pXG}+y7e4S;nizuu!TLoGkkwIQKCE1)&u>(6F
z^%No$+o`FVo0`ZOZEtpWcQe8tHvFDIzS$wy^-H3l1W*v)-dISLsE6KWY2R_QZ`ho4
zY_})U>bwsKY#coeIj<Hw7ZdAFp{5^8`TY5_bR?j@u`yt0AccP_oPca-<>kj4mWJi~
z1hcDYR_<z*3~97PgXe#$L?P9$t%9dm`QI3R7@TWTKxC=f`4P8L&}kE8ZcCAVrX+O1
z8;SWcK@BPZJm)Fse;wx&uF3?+XxrG{7w2;ev2?anbg*^`J4EF@5r$xbz_q;a;nz{B
z*EIkRp?`q&Qao_8s%j6jdmOo}|J%1)CFA7s5t?KTz3*L#%88|glWgL*gl-f6E%n#Q
zG;P||xeRlNU7<E&N8xuTzeiUTKw?j3zY3d0fQ#Ek|6D$KYfkCA?B?bsh}%j}zI=W8
zY|}FM2=X{I>CwZ7-h`gGq7-iElRMnY0N<06^KZ!Y3Wt<YlpD65i7Z?gAP8gE29TgB
zq4!x7-1X5~c-eDC!eoLjaMXv6k<9YGciFd!WMtygAaYv%>CYrotDGWMr=U(wtvzKg
zK|x*#5Tg#SCAd>iFbk2x<J$!>h9GBbgTxifk+X_!UV0zHUZS0Y%_2;M%I~E=A<ytb
zzJMyD|0pi^HufLg8=OO0NAT?o8^q8h!&`3ICDzW#Ah*e1b#gzN)Y#i4L!04|+e>vs
zH8>f_N~w#L=N$(@OAPa|<dY}Ki@|3L_1i0lk$?)^;e3fZoE`TV%Z^rsLrsErY&pco
z6k(pA2Y-M>!foeyFW90XFS!m_<Gq=r_MthVyg}S^F%QS&&99KcAkGhcXGnNXq`13t
z&f?kWG2+MKk4ZpP+d-TDupqCH=wJuG04OVq4Ut>5c<xm7$;MW0V~NZeSOc(`r2(Y7
zmG3&M555Ey0baq|0d@t%5rTNz*lIg6Sbs}jHSmx0tK2Oy2O)0y4<g7+E5sJ!r7|kG
z&P}~CaCNVF*k2>qzx$qg`s-OYB>N7L$KQsm7e4#Z`d=PZNk)EZpJjT8`>2U5Z^dm#
zKhjD~k1OjAOE7r(R5dI3bk4bl!-%ng*dho>3$S^|0c4W)>#|d2M8r&|Nl9jkHFp8W
z^~P8UPOik@YIv-`8lD6&KOP{7&rMxDCX@r>3^NY3Y7bkA{pW3HWNM%Kv5d%Kfele!
zZdm!yjs@qOnR98^*Ui*-I(p*j$K+c-r6{^fs4W$}FJf(mJ5@t|N>e@jYkerZK>z*4
z@_)cIH3A_KECf-XAmsqFm@o5PPn1MvW=9(Wc5n%s!}xI3&}CV|gZp$$BM!1Uc?vUo
z?XF}x-6f4}D}QAkd(-*h0K8{79nrPdO_Rwjo|cBjU)tp@GVKSlIn+e*079$lKMYfd
zsnX>HNrn)PcR<$O1P%wn?_5$sMC^8CpCj1DQou-V6L-nMew3`oy!^h47TzZ^sM{o5
z&z{Q2$;7Gml?#^4ydQ52&;EBY!7{V-l$6}8nxd_bR@UJV^Ff3^it|;Wk6R&^kb<3{
z1|{wG%=Xsgn5oqg6gma)@N&)on83IJ^fZgM%?Ir34D}>f1vku-BRS5ugVW`><Dqx5
z>Fb*PHkq#yTf~R*klGHv9~Zn9@bRX{4?7Lgo~73|JE_)fyX+w1cyf@)BF)pxh$Kv5
zSdALDs$HS-ThQ;6oae3+pUsZiA#ZfH8w-_bVh}Qa7ju1r8(;lT(J9gmcnrsh!WRvf
z|M3uf1N_?V1{?*x{=TLE?WYpL<)WI5u4EBm>P!9+hsaAYp*LRxxGLNxG`<MAN?)PD
zXzm<prv+VhhLmoAL%i-92p>p61EUWy)yDZ62>r}hOvxwjPcaA(g8-#VRB3#C0-6EN
zWJyk31YNqOjW5vxt<3=Ad5Bk5x|9U6?18v~K~lzjsz8PKEG5upMV5?V{bKLhPjy6W
z7RwY|Fx1dOP!N$@{zyFZYqXWC4auoWWj!Q9^k`R^tM}Q#BD~p21`lQZt4Ifqg#QRW
zH39w9^-p}Z#RHnb^_j2`hKq-#AzivEZx$V#7~|=b2+Lk*XlTS!p%>bMuk`8{{4$%?
zzPZFJKk$Nr7=CIAw?gDDH}bbiiht-!#7w;t{>~^$=?I|eigQsbOJrwbm8R3YNO8NE
zcZCJ;44#DTL#Hq|)(Yq<z~mq4<z9Tcj(LcMJ4;BS?c5U9W76V{D1Z|e%1~Od_i}0i
z*QGFi?xYoax|KM|S#{r5uAfNuv~anq%G$rTIL<A6E7n)Pl>q*YwSn0l7t1gd#Hwwt
z|J4w}=*yrRcSO4D_2XVRm~;D#0E<Ep-rSLb^YV|cC72bf<OO{ERU)>S4f9Qp{gNkV
zN|nJa0E1&XT1!*$4XoWE37)Xvy?6RyLtL}$@Mh_CU~_+aTv%#L*zzq#*M%Y56DU=%
zhvBOLcgSB2Yt%p4nXStIGa|Dew1z0HXd-_)zAB9T@Ad{%w83dt@Tm1u9-ewE-zRA}
z$EA27gjx=iK@W@KJ=)J^nM(1Xc!^(fz2}UgI%a92zYTMm2_Hbkg~|P}UtE2@>^_DA
zE4X#OzgebrswZ~SE?hNZXf0&a?d>q<-3GQ)2s$xtOQB665XZVG(+mer#zv>yw$9G6
z{Ip+-i%EKx7aJUdJy)rz^hazcx|~?^I(V!)7UpIM{b>c-aVn%e1zsm`%Hk;k$9pcD
zy<1x(!MOk(wCHrAPZgzZWqpm)Jh|cgL=GvlAL7#!h;2rHKTMwIWo0E#YY3k3T34Ve
z3!Z$wKSPvW$XW9elP?33ER$~19xah-t5TGi#Pt&<!Q!2dmULRJi;y@D_|_hBb9r%D
zr+s^=`M*Jv_xynnX@m5OozQe}4^G6U?LObU*TkQ{6NM%>iuw=xff2L+rg*Iv1rMmn
zQedGPF1o9(Qz57Cz6W?HE4H4))1uBNJRiiltpwk|%LQ-og*fzv<ZzXhHfyQaCn7xH
zTC2sXniY9?psKwPfMf3DeKS1tsG^%$v!3)*PI4^1F}`_zfjE%9hmklNu!LjYGgkA!
zXxa?v<q`rB(93a(Icm?9=fXnMNxaOtN=(6uj6yS5Scjvzyw8e_@PN^c(#hFriG8bl
zpiAyGN>bw6jjO?hv%gs)AGQ^X76Y&jcJoiioJ<rCt^SdQw#PFxHqN<<>+k#~p*<yv
zm^!%Xc<!54(*H-%U!<hJy6zdPwqn^;p4FLNYshX&dp|X9(IjZN%sbe^nI{TjDDdFE
z?dtC4$<Kp-M=``3b}+yIXaGA_c@FR0a?(F2Oe}NK<^@!Az=n#bD}vx}gWHH2(B23L
z697=%#Ga`|?P{5k1$JJ!RkJ&8sG#uQIRQWOrqr43VisJlYY%p+p9^8vRtpI~X5^9e
zl)SZMt|2dwkd$O8WY`xK)nULW(e*^`Mrx8FdoDTxGX9XkdL}J-SgYS1+I&q~`A>K`
zMu^o!=TEqHF`?O@nLyK<*jwP+d_kW-dHXpPHcYefpjEmlM0sG#R$qdzdh>vblWxK#
zA$SlL47}=rIH!9Gq({dG_yc$6<%87rh4eQ>6PR4dH^>xa4U$B^f~<cLTCtxM<ZMSw
zH9+1FeNDk7uzeJ)pZAU{82hgXK@K;rJ#|^67)cramR7cz25)`M)|8_b;-xU9!`XPD
zgfzeLC<)>jwsQ-9Gw%hc05adsUFF@+^zdXslO(R^5`RLlri9@p&Bi9hCwR;%Oj9Vi
zi@IRDGyjAFV3p}SV_+5P(fexKohFWta~nu1j1C!FSjad1W(qNTj|IRx|7CpSO1VS*
zLO&W|LO(*pGBr%+d<bwVQDot(eiw|3O`pQ)$~;CGTtUBJTu5!SSUH&_K8CjiDc}y8
ziE^u2Uug7kQ1g{I+Gyk3+k>=%n+=HsXqys&9md?tP3pqpug>hg@+#{&mXW7835x(z
zuELS6&G><TcY7k`(bZnEUJu^khB5Pbk7#d@-=YP(1GZ-SX#X-NtxuO!2RF$zSn*+{
z!rHc<e>mW@7a7mDsjoQfRZQ?lq*usK!n71}_8QmO4P{W%X1!^P8nWMd`hAS)KAZC5
zr@ly;g71<8H*~M-^$s%MSVZvRE2WDjV)zHZ_(}vZ&ZNd*dpVeRZe{2wp!zmB@55@k
z0C2$qQ4vx<Agoc`t*j}m2)QiQ*!U^6<&dPO4y+57Yb}y>*D}aDMBx!1HW!$ZeCT=~
zLP(I(W-MDlq+w$MlhQs-pioQ>NEX#AQI%=22>}SUb>)Xp9CY$eT2;`X`$_H3DY8M~
z<I_YAtSxGl!mi}A?yaKC$6Ax|b2SP6^jH)wH6{4LST3gYG5mBqrX(a;XtC9hZqm&_
z<^<(A#)1M4{y}SEM0ftR;~Oa+pxm%S_`YYqV>l$QVwU<z9)E`}f`WEgG9I=q6xc-u
zrxIELV?n^yrcu(RcPk0F=!|bC1$)2fFUW+rxRS(SX0KmM?S7Kk)0LX{?6TB-ShXJ}
zN$O5g!Ev*pKD8fu_kL<(-bS<WGS#h&bk)vz;_nMWYJd~0ynu8=mwojyaG;|?s$^mt
z<Y#4uCQ~4K*l`)w*7+uAB%mZfcT2KXD9{<qLr>4NAw~e62r)hPJ_;^rDO21kgPca#
zd>tX9nw~`t!t6Ody*G*C<Ev!UeFxkoj0Y0tPItY80pAE@lko!-sn_vx=-iMYsnbzS
zaihS}SxYo8ifxN~>J{M#mnqE{{UCn2O)I`DqRTPP2Rztu`sCX&^gZ-bDgj?POuvFG
zn1m<BAwAgC$O!Q-@R{K_>I6|Al4j{&&$|^J+$W2hj2Fs+y?$dJads2p@n`c=o&4N*
z`?#k<@*$+F7eFcF$}-DwnW|zJp~Bm5UN=*`V{hQuDW4X@^7aI*Jy%}8c=_S>D)js9
z)m`4TY8viu&4fd(>Y<smZ&b3azlm6fUv@v1&uzmA-VqfeLg1ITc@zzduQH$MNK8t>
zacels-EZCBVm~=68UmtA2flfjcn#M14C1}rDDFwXTLd}lIL$9YKAKyJ+|bsr=iI3q
z#!rY~>|!79Ah1pk%>nmvrWe}C<1=i)C7L$IxDuJ%wsCZJSm8fCK9A&Rotxm0c1wn$
zSnvG5HY|WxM%^eSn^`{qH}u|BkFRJPAv86>4p;=UMl>5Uh*9RSp{d)9F-+-9cw<B-
z^osE(d2FYY>-V`%W^EG<aV<k)^f88|MobMo&+Qm@jmL6jEq)K36i=+jqy22m0OJG~
zW(Jy1CNck#slmiO|CMV%*Loy>(IfySZL$wdOrEU^S*I;pl*Rdx<Hwl+Hj+&6+&n>|
zK5N?N22+Q99NE0DS^w=}pe!l=Qkqk~9g_I9`fC3nZuhxx&-^J=oN(K_%CHyIDhBdI
zAe8(Sz~E(;&&X5f)q#|)@w<>obC`-<&=Kjsp$#wdGOzLIEeZ1<7#_nwB&h#O8UIJS
zj+;-qns5SEAOuj1pAF9=BYbmdP^q08Md>MEYHAjL0&x0I_UQRJy`&LPNBz`|?02xB
zctkg{VmcKSPn4RWb>PgY-DU0dx|rF(vdCUL+x>bn%VL3$8TfXVkoCQ*0z})DthIQ^
zN~@4z>9-t4RE}}^lgLm|!!-pqmAQM`F^6G0k1gyf3bjFLY^}S<qABu20MPW?_tB({
zrNGyep*;5XBSt_sFhx6qaEt(&Ux~b%r6`ig_l}#G&c2*19$FG2M?UwWHReEC)M|@l
z3uAn+c_UJ;WK$NkS4Y`*u22qS+{tfNn`tKO!1CI{uq0c?tJMTPHBs{%GZT}!!aG!u
zLHk~E`|<x>*5_S>@4jdh5!;u(QRA(V>{bhoJ_8UK)BOloW15=A6!GzOHG1W~RCZc{
zi7RR+fBTle_sqP|O~o^N*Q<&{CbREqvkmV<4u><sWoTLU^uaDcn;o*6ewo0jQB%tx
zaV_ar9d0S6H5XB3AiaP$L4^xZNF>kK5v{^pRAb50ulcEogFt9)4xn3K)28`w$$hcb
z%uUOIwm+is^(fg?h6ve#W+ADTQb`prPs)qoo*RCVfVXjk$@oRPFeY%rQc%I@4#+%4
zP8xg!wWw@8{dTz?dg}n{s%011Wz3y6da)bQ>tM|BD|7C1@LGn$Hy_p`xqtl+wo=X9
zMX|)vj~c{5_$YAH<NrVp7LMKj%=tcTnS7psSd%2M+aXI1UM85zCJW}uGvLv382v((
zupugiOp>rA@4HB!P)=g-;(~Oc)D!99-Fm7G3Igww#+iV_9)?h*+kgLUr>x7G<m}G*
zvUOe&P4gcg%#fgjmTfu-PH>HPIZa3E{>+XwanEMM0*ZCAQ-300aaF=5!SnKOK-Dj%
z=5iszM<ulo=V3J5%T_1AoIKTLoPZqv!TiOvEv&S;@Az>}@`aO*gb28f*K?>o$Is(j
zV-=-SxUC#fQQ>ZAmHn>~)A!l4Z_<)+7Qg4-elA>6Qqpdj;izLo_eo$p-`4Jk?3TLj
z$A_|dNxg0N9jbqhx|G21&E-GEbdu<Hy)WaagvgfQ<7zM(5+k)J<h$OVyJw68uT&NI
zX?5vimM>f!9GCrks2Hb1abihk7jO=J#3NwgjD>&Jv)$TX+N4O2;BB)E76Jh>gy{6q
zm<pvGDuITm&H7JZ^yL}wirAOMC=usJWBlBE+tnO*-KLAGx;uqRu-NZDc_SMlA0=fr
z#<tnR{U5$@O0v8+TeWf^v)^K1;X7r>eXkk4vs}$~o)gc|KsDLK>2kLevI=FozQdXO
z3_@`~=CG~x8$)7nL8mIa5dqFy+XVRLddY<iiPMjaL7ZZ)RHvx-fe_ZW1W0iZ>N3Ba
z2o)PQU+bv8%Hq`Wtoa$l!wSJ{42%^bpLN|y6WeSi6&XVm2;B55j20X@yE=+3_vDyr
z6{cp8r#Awe9h-UMbI6DAXfuF7&X|C}Z!Cs!A(ZIueHsA4Hi>K<ca{-zI{y=5hV2_(
zNXZR|^_zFoW>78u8(1yxt?p|FM9la<0K6Loe0LaXBx-9l&IdzRkME~b^41GA?}+`v
zl_p+(1uA^cG-h|BHs(0O<graUD&9||S?js03jWWnqpbkFnSCt)3dpg(_pVQ7(c1fD
zq6o^@Sa=qvt5sRKaMs0kELk&#zs%A{1WmM!WYL>tLJrRo?i819V36B`lT@)(_>}bC
zxXpCnIH5;asPXTY(XEwgC83o61_h{rXPkJdyV#p;V9WKpK8u9+lA)c-!B)sxNH)`a
zGNHN9{s4a^Wa+$DioA@|CwvqETOk2Nn-UeqMSQ6)x1_J%*UNTz-$gY*p#)d;!vm0W
zk~j;JQ6fEZS}v!jX0XMVzq0VH1PDKbLEdXmM+CN-8~xN&QnwD_3XlX*6v<XZr%(LR
zx3$_3jp%-cD;y*;^5UesDdk=@ewM|+zUd>6zNa6VGWE$ISYpL6;Fpl$*e^F(D(xFp
z7ZQkuI9mJe<?v}D-zdC1(uZ8W%)|LfPRwYPWo_3mSezTc%s;?Cxq;yO#d0zI^h1CN
zyn{UC*E;w#j-EhKP>ejMiAmnUw^p4ac+!|2;0uG018grvPKj>Xhcsa!oQ^AWny0D^
z7H@t?E_>WdO*lnz&WBv>f)p3X|MK$<6tH%6vw$w+VvdUVHkTN8_*<J{*M02ohiKCq
z{>1W=A2)frls2`Ix<~?I6lV;5h(L`^*<`QFO;3QqE7uZ@+W)tFvO8<KQRgItV|fOZ
z2;r=Tl5d_Om$2D$ii1CI$p?0Dx^j2IbKM?NULAv?m!i7iWWwzEm$E@~_S}rI%<NM$
zEsj2aWjGE&)4i`4J%Z}+MVnupH65H4@+DX^A=yOA=^)cT*x|_unrHCM`p&%TWdOS^
z0}rpnDd?Tc;Zqce5gvfyrm4jX;Hb9{f%*9QIsamD3by*K5~zrNdlI&=G@Ap_%VjSA
zP2ER-l&cH+&2(kWe)B53B=lzwqM&sS@GMS{>e90Y1jFZSKj@5O)*KYixF<r1x(E78
z+WZ+KU`Sp7FK|?x2JJDRXtp7bm|tG$msBHP;d=yrsG{r_jEj9=<`?~%-c3UV!kv$o
z$Wl+XeZJ$MP`Y^Z<BU;)_6H{W_PE$S6s{`{X4)khI)?H$T+ujwy%rjKeK6Q%3GBfb
zy0}Hnoi2N`QyA5>`~Q}d9)s+V;*K|71L?qEobC$>UnHAz5r|_xdUCGeqlim;Q}%z<
zp7Y7plp44cN6#P{j#Wp#$!WEoZn+SWnwKiWvkA=>{Y8%ciAqCButS<QFgXY{=uNe<
zaS>8^%{g1&bXXL2S0_VIhvbJC#p}yyR8EZ-ZLwg6WTR9GdILW%?aMFr<N+86oDy9T
zUl^z7rZE+!SU)>NsHl_xS5yzt^3xu9K&Q40JXu%Cr591Hmv3n3!Ph6)X8Rk&hfHU<
z9T7B>%-kK-Qt<2ZF0rZK*oX4>3k#0l=sUR^1Hu>qJ(@OZ3uUb3Mbn?A6fSRDA@UgT
zH;KQtA%Qs7fP`mq8Yb34PnU)WDp;I=Ib}!S+t7aiP>H87UJ^#I=HjVL*#U_!VF4?h
znob9cA^Y!_#9uK>J0|34uckeEpRwjDvcA<uiud>mybcUW6L%Pqj2KI=3STFa`*rFd
zxr4cNzM8$5&M5FUg&-l7d)wUqJJ27(Wt2N4S?*jlN=`~@^b}bL>M97h@M}-sH~<wX
zCjLwCTRVJW{gbE>W{RePm>Y~KT0vsO?Osbt(Fjd?k5O?FipY3%J~!0=h6kay*x1-1
z=9}Dk@XHe9W@43bL9S`{-XZhw?>A@bC}vl~F#q@Zt6p01`Yzs+d2l6{Odt(_j4Sf9
zDq|n&s3`1*DGYqcxJ>w{ZnS_!i^G;bn4Z1sSD<z5^Nkt(_+H^s-Tro6^Uw7&X!MV2
z_Nj=A6Ukl6_C;0$c3b*~FtIqhV^DgNfeHSOPu$fYt!>cI=n&B?$2%L6ssq5x_Dv)y
zc)45N+Tz{y%TOoHDfcH!nXFxbcjFxCRFIW`?<Kc??qH_xj5DI+b+yoT9R%1APb5!W
zZD0C*w!k~wJl5fk9~p7?S@-R}7vn%UK36iI4(=kbxD|5qtTSA2<&<*TSUuggwG>X%
z_>bNNnZNV&O6nlsf5I2~u+!~J9)TCA^E_aZQ-ou-DHSwh1C21DhMxe17FF1kqa$Bi
z2KUHzjvCymr=~MJRhwz4?LBABy;cniq3$2%o=SJ)g$DBMfS{y`_^$*9{!*t8$)8>t
z1c2c$3$5QmE_hZdcehpeDha_!NcO*lnk&i#J_Z55vv1i;T5=}vobRDd08p*jKOf%7
zGZS@-1=CxO?_Drh>K4+aI740_x&>)<$VI}lpA;IS3fXbOBhV8Yg$!)!jZN}okS(EP
zWBk!XD$%Lo+V>ajsRiQrvx^3NAK02vB@_!cJx&TDocA>OPz2k>1Yx^Lu>uOM<`}9S
z^Nw0Fv;!GGa6mo3Rtn0ntwLeSgVYtOVh8ZI_8*@b%+=LAnQdpIV7B#rf_K(|Un?}3
zSGnxv?&PFXoWAma0D|C`Tr@i#|1s(F-kbjDZilj&@uQjHNccD~)}3~qo4~RaS2hU-
z*B}rG$xXM-FIt8F!%u~(dFJ2#(s_V_czjXP_R@6gx1n0k0(ZE5kC`Tz=E*61wtl5B
z9mkr(SocY+4N&@dg2WLGWtSbXcfv^5Nqm%&B9(9OI8O2wp;@LReVjv&CQ$_2$uCR3
z_4m!3v{H?F|F1glyStCe*N~<BFe8<)wU+Rfu;OQ_ZaGF)J4q!u1@MP*()^<WUn5F3
z0t%MCCjP3@IlntUToH#6*HIvWjs&0CB(3wfnZb4oIGzSr(Qm2bX^Y?s`g9`UB*L5`
z<mS>9t5<9G4Pw?#INTOuTM78ksWR-{+8a}r=;MF#&TvA%^56USVygjF6scnp7yiHO
z0ybawT!gWZQXE(B;z6{JCL-qF3A`J@lg^dR=kUBnvh_0qKJ=l*=pE6LRPH5#G=FxE
zZSf^Ba`1;(sJ}><AkmlK+{EmAMMd^2n|r&v4=yRvvrnlPsqQ(OaE6PxILvBzM{HdB
z1*0={T$kEf|Marp#73GY|J{nL%b)&g=$r5h-MLcxP8-?;JD0mjd0I~sRpH|tY?vsr
z`HP)VAW<KyPkbP*BtSgTAEcS^O~fl)Zw_k6`R?KF%)_IqWL{Ka;+fZiurR+=K!9j?
zb}Y}}O4IH_I61)7fH>z#iuO`L&DP%JZnMrb=$*Z|2_@?ZDXB1DS_*AiA-cq>@Rvs&
zxh~(P%Ifmt=D&hIJ$bZ(s4io!i5#NLuz=&m>Aa>bzfvPP1<gUc`{P7Igo+=Yn2;k7
zh9M=EFCDOeeSSd@@0}2ug{}w1Gzk2}kNJ0AzqNYm<SD38+@t)${tfH$Wx5*K67c!1
z`cf?zDpxC<1C}Q`_T~Vd$f}D7bFxewj#28mtPf{8w1uvwydHY0`r#2z%`1y#G0@e-
z4^u3&mq<rhu+X1|<@2r(m``PEt3io&d6OqC!%B;wcsuBn%g}5`%1xq$*VChEA)abS
zhUM)Ftr?RiHy2LQ2C8WLJSAw}FlIjH4Ro&oVtMFrkB@`GJ<_nUn=G;tdC$5#j*~^V
z7@!;=Lk+B|0jA#)F7v_pBDoXpaWcfZQ^OMsyf(WE?rXq+lho;O!f)!0h^1yXHC3I`
z@`GPRpA532D~pn;<HDd9CHryzZa5QZE!9?W-0?x2+k<1#Qea1FfGNp)#!0m+0K}_S
zJmvR9tkfB3n@IcqsjN|@$RH8<Z&5i;!eDezMN6*JH0SrU*J%N?lrB_lD%1Ez^rh&W
zx~dfj7wzh;+$)BLklK8I|Dz(EqOFX8?rfAG@&GUH*%-58`rkvF4*Y8lH<7AZQNRy`
z2#O>p`t)2T4AuV)t-d+r38hT0HdI}FJ_{Pp8#rTkgxg(;DGH($B$h`OdmSCSZ<SYj
zpLT?ZOS!1NA9%hZcSk|>HaNoAB4wJ;!XHaSbD4fTl&x@=c3Gz<^!5MtZ$m@FOa@`g
z?*`7e$)X0nB`w?_wUZ>C1G@siKzHgKUn><q0)s|Z%##zG={BQ7@7?h}*-%WF`N6jP
zJaSz2e!Yk57jo_zLn8oFiYbgtk;3Vx+Urj*OZ1%+w|314rz`;_z*1a@vn$C0PC#Me
zd-j$^K~T1YAmC!r_6KibT-XcMo($GHo`ASr+Y1YNQ2)7wuMDED=pc;H=$w}%iBXzR
z1GrNS$Kz<MX~1vU9@-p;wW4#{29`P;UjHokr%9;~3hJb6HS8+M+9RbYBUuQ<4kpxb
zt?EQ&(;U?Z615wCD$x(fFNKIg*4y@gKP>rbXZ?-|PJf|*V=-}(0s_`I79t42vjor|
zVhq54FJJD@l6<dmT2_$&L}y=7MKD`-S$f4D(Z<fi-88Z8W@$92$-AXq^6RCH;h9<S
zVf2yI;EK)CWMjKT^K8TowrcS5Qa=W4R99Y7;$&6*=4YYz$K?N!qimZZEO@3@cQ3rh
zE@i9r=p#Db*?$c$qjb%eUtf7?ucb(jxAfp8K4(wz2RBzS&#1pQT&3Z`<HH4r33Oj4
zA%5k!tr`nb+^H_mK#@fH1Snabi{wn<CPNXhmZMNcQ<D?vD0bR{u*rpr$^75iTv31Y
z!F?q*lst*p=?VAh$DVS2Yk*FH0Yo(w@RD@7Z=WQJ71B!zfyp6$%!b1AU^=*j>9nVw
z8O`)JVWZ>pisbv^!L9apCrwa0&Us8M+sstORl!s6v?I}SZSKSl%cNq#3oZT_X(Ex1
zYM7fHshBB$L$(mUC>hZyN$@{hzm3BP*QM%i-_G8JYJXwg@DpdRR~8fn`egf(JAAxI
zw-;&DMjum55p@lE(mP0I37l2)28&yhIc_3D-l!43E+3YyLegS%H!ZKYJEcCM1uvm0
z6|=OseVoDsJ;gBW)UOio^HJIx>Mx0J8tN2YeTkFA4iV^iI+xbXg_n6;nA_8eV6nt-
zv53egE#KxF!fv~wynBb3a5-8zKZV9!t$0dqMG5HT5V!<=XA;qjo4qp!`Q=kQSRW)o
zG>VaGSa2ATU$X!=hmwHw*tdalF}lu!ngcqjqDS!7;u$o{U?(*mfDR?rClA8C&6JjS
zmuZf?k?C@Q3n7uNAbdLQ7Cc5bEMB<gW1ls=Xg$+3<VTX-^bXkP?l2#=&FYp}3UQ=>
z+atyI@S?KCRNfC^`z-#YlE%*`qNv6=kU2SQ%Vg^WDP|mRFd+tO_x%j*!t3O|WUo_~
ze!K^xR4b%cdQbRC%JrdiB^HB8_>*0(ANQDmr$99L5@Nd!A8(g3m37owrU9K5VU3!1
zZ^;dx*4(8wuK&^HGRn>_9842#zrp=T?e|_C{nh9FA0l6RH=EdjPC6Qq@#yAj%yqWa
z3&HTf5~^va^v!t)SR->Jwt|!ECGo3IAH4EkW>#}&S+a8)SlJ{SlELW)CG7su=Kryg
zH>D#sfjy+?wi%DYsY!--JnMsy;M!|;JG*-aznB}wvZW*?8B?SP%1ZX1W(Sj-uruho
zB%6ZC04t}T{PI!2?(>a#BRWwIwX+o;S1HR}d+IM$7O)qJ+-P<b=^I(}Kji4a7`1$r
zz;*UmOpcfqw7cndXf&xtPa4vC{b`TnJtO!Rn>p6xD7TJbLb+_?$2Z9HMWF?pJPALo
zNRYDsKG0Le2;}-e5Wj6H&gEX!%(~Y4Dqn<veg`=*k=bv8tDwI+MB>H;gnzhP2yfN?
zmP`r+d`wm4@T$9I(@qz$JUfIB1)#$sA+Edaa&11?XpHVp%O48(W>$nzxzX~JaqRDR
zsvhCs>dT7%r~TQ}z{iaF>qY!jmc)Pks1UDjG)QrfI&aTG9^hx4>K5$mmORD9*P0IA
zYZ0+QGgUK0RxH5J3EBnd)Zk}D1<q#8ha-3xfJI6^zc>?tv9i?Uom#MfMu3jBoMMiK
zirITpYt;}_IXVVfRT%!jN)g}3j!YMnVI>Vz*(DOpvWMp6dvmS;O`Jj@Lt&vTm&hgE
ze^ikYfqKAffgMG=@5sMJaw`e=vMu<kWn^v(-z$USUlDhrI{3o0@%=7LWtRASN^BY#
zlL-ewpI8Wsm>P6S;kpGRN)Rd&rXi!Q-AoYHrbEeb-k!yIH`y}X_2du=ajDXgK9%+u
z3&jOQG*!MI&gq#<4EJOq>JQ+4&<WQ&FiI4y<gHWi{p5vaT=#!$mNNXV>{nm>K*Q)6
z$7_gvgVO8&fcJHP|MmG{B~IlxWX`IN2xKW<j!woFz%(}!uG+!<dV{e?YfT5c23{%`
zek6Jg4N{U4_Wu?xFDU^}gL~he;DW!VXkP&E^N63D1Y}%%DrsrCaJstGNfDXFmu@Jk
zZJ4Cx2aHM9KgsB@;c0;J*{JqJQ4pVGcAxVS^N5&G0_t?##Gx~@$v<J}Yedj<t8XKW
zuz-?Cn|5F^YeQ6+zwVDDWw2t*MY<>;manBB2LYQFHGnLuSa}K}4K81q)WSf;#7(*u
zqGLnR*2)hdrt&DY_CHdDpL>>{6j63n1ImV!T$bRTA`FW(%Si|_tTty4Y9co5WSQ~5
zQ?!M1OG;k7!x@K5mu~j_GfuqbhCV<Y<dG2vcIzdoq1K&#z%}67h6jcGQ6T{~TT_tC
z;vl^s2i2$NxPlTUXe$X87A<KTn}L~sT@<=8g96DJ4pd-+kICDXs&33E!d$<!M@4MD
z52nGQ-fm9RZ_fC7XZ&|v@uF2vn8{=N34CV+7oiaql<dLNKo-kG=k{0swhZ2_Oky8`
zX3Q1+kN#n@t2lJ8ffu%MTGw_#qEzGn+5OpoB1n0_Lqsm!LF|3fHhDD`15uqyTq}f{
z;Z()%QX)&!q9eTLbPP#$;w2sNo!`<tf@<OSqlbtt2%U2~_kcRMKy^HbjCCew<Uc(H
z#kfW@VA65VADLN7<L9uFrZI|$Hr=o|Wc;e=i~z3RJuObQ>z(SB2v2bkD>x@=V3(yf
z%I@E+O(rf*O|?cg{9Z@W(+H<Jw3sLr#T6N@C;bWPW5ngoNp7NU4gnnwhd$EIX9ex0
z3R}73Hgp6dD$S4dB}&u9Lx!WuR%S=Ze%4)4@RVhloI^4vOYx&EjD?uBITtVk4LO4>
zR0ShB3MPG18pAZH-&F$|qTC2YGOL}C--SY&oh!@k`7ukht?z%$zH&$5D0F;hi*$D9
zjg<wN;LBsf|Nm()73xXm8HNlFA*!+2j=;bLNZaD#DZPVrU5eGKmzs~LW0gI(`I=q;
zXVOvyAg-M!tTftyH@1C=C#i?4vM{sG?BK&8@;4J#gxkPL<CWqm80nbXzN0wj_w2T1
z2HL;7g`d65hL$U}1LprsiZ#8DAFwaGw;5Dc*4+~)WuOhDe)@rA-zxaT5aa`sfeAv)
z*eMasr;dI>FO9ps0iAvW0;U|q{_`HS!8o6tc;ae+khT0V!`EY#r>ZjKdw;-0qa@1D
z&Y}j8Sq<4t^hkMGqrU6f2t}m={XzA4byly)XNTQ1|1oSHZ7LE~bo@r};vaznXzrs5
z9O=?}^I_glApitrAl-bG%`)&T4S<9>7%L!kHdM%wcn5fXRh2Lc_+&aDYiH*7CAL%E
z){FG}67Q1tt4s62np44y%gnTxu!sw$IJK?xKlRD=GgYKF<sTznp7~te=`qpfr9Pl1
zAi;qX#ONug$Qf>fW7R7RT;WT%6GsmbHAb4WP=DL`dHcz2uD4z`+lE!*gFp!#7X%(2
z42u(+?0}24xrf?ouH2V1v>fm^NvbG{B2$<|TQvJ`@w<g`rp%z@M3<Q!c?0VM{yV)W
z`&ecw)AQNvr)EHN*yC{aT>`-KPC9hzqV>+>a^NZF)1kp@RM3-GQ;8xG0iTcPk&z_W
zuvMz)ryKF4>|u%9Hm1U^!qXpjy|k)r*d(=WuYmTFJbD*Ca=qlopfVx`%XhgKcQvE(
zrMN^rc>@b_-JvHCe8ZVnE?vp3R`!<jW5xkSDS8-#>{Tz8arxj1WN5wnoDE^q?-zhc
zJJ!VfPtOLl@pTmy(6cYGskB2oEP|<wy~*L2y|Q0{yCxo6FH}N8EUB)8d0TdFkL_fM
zFWfhMPlMMHn=h<q>dWVPan1w&lcl>5-YI_EqXBnd^ur|a>nob54Ut?F-X-%*Fqf|K
zR~O)mxA~+Jkr1rzAqmGA#suuDN)H-YE{!5(!6RPD-`O55Xb;yPy!X$~Nf)5!wrdRb
z()GY5)B$FU*zdn{%$+D=-)G<p-ZZi(ns@RkI>7t&&MSvbeP4WvVG%@q_#x}TDG)g;
z)ZD_KLmgryrOFu2ZX&>OpqdGa0JyjVp1`Z_a%KOVi@lEo7Xg$nbxO)GbX@?8A*dqV
zH%*~kx^waYaiZQ_aNNrrLF~myz>dsyx2~>r6-<9{=$@YLU}lyw?Kce-!LTf6K?=^b
zy;mGVA$*beW-cc979(8{H-L$2O!-ddGaP+96fc$#APp5E9XMzEHL1kZo1nLq-kUby
zo0{6jyD5P)MtbOjm<@6=Iaq1c_RDS-vvvg7Pv0-e2KlD35w&s=r{culRA?~1=97_Z
zg(bLZBcOvz!AzqA46LLK%9m}d2xke$N{_lpBFeYdeRfGu`g6KVITWRGL-1<U{nYFV
zD#Dc1HZ4otq!&OMC^0D?zgdS3zz$XKUwb(0=jY3q-s8{!dr%4IHN(z+=Oxif{}V#}
z2B-|XkLKVWc}2i*1Rw@#%reM-TZ0P2qc>b&G)iCSx`;O*qexl&>c`76^v-Dc-{O3o
z_y%QUSK2Q4;#yEk3_ygEsQjMDu6g57EqeTPR^g31+Pma=AKi0gHZ=fktqz^WSN=jK
zD|t{O+z=dqGIa{$yQ_p_o*@UD(;@cdPa;<&7Di?nCoGK@ze53RKgc_3;%;M7fPKVK
z4?TVUxYt+&B*Z>T!5nW@hnp!1YRNx13R{p8>c%WPfp{O^X0L<94ae$T+t>ewIK0}c
z4#xi0;*k9QxwJl?lHL3UBb4^yKS&bKJXmQ7`R3=BdnDC*svLQk?hX%)lLY;cnim&z
z5{<FtH}VCT-a-xAR9Nh3?4+uGAt6kukl@-=mwviu2M^~UE(p7ap&nzWAr!QxRha7X
z2KT1J8KsKEImXDyBxuGy#L2=4KdbdH9&ts0xM--N12zp-ML~Z((M&|n)*-GSr6f|g
z1xY+Tpq3zA8Axa@mc<~>0nH{MgS3)N&kLia1b{=buoLT6-58xI(N<xYSQ*(7XBGoy
z{HtdB!`%6o9BT$bCh_4?hAmv^XLAbf&xBD9O`>0K&<OL?FfL{OFv(W8d9^Da7C$%D
z*Ct1&ofAnF%e@o*LuYYe0RZn~l4SE!hEEY>j?yE?7dA-aSFf@O>iG0bg*yd0Bn!vZ
zm>LrF9aRveGIO5JU8Q8TFF0q2M&(tdc*iiQu?4xKJ=3`O8lf**1^*$9KzAYaN#a#1
z@?Jv)G9^0=H*i3h%7fCH;Rq%vE&wyGo{(AjnNC&o3mWc>YZMAWdY&%j@gvO4JRaz;
zt=E&R%Q!`;LGWQVnEYJp(U`~R->@D6*4<n&ydWew78@Us0S1ahpV%<Lp3~bxNd;X&
z5QA`T%R@PcQtI-fehm9B2+5KVsHwjQFqZf2g|2;@8HIGFgiESZOu*(Y0TfRFSkCII
zM#sEe*YS;jKx88!gX}=AV-oeE!EnXV0cuUcVw6w#k?EYsv-k{rg(suTzFt2{qSeR-
zRX}nXmBgQ=X0Mw-huqv^@_y`b)XNHVo=V#`1L|PGSN3?p@uQyRqRS#vPnyGQ-iOG@
zZQkzILq_q0C-tWitC?q=%gGw9zpIKWdk&5Un9rXHokv3~vS*~QN=`V)g*xUx!T2?P
ze4G4sSq=H*-@xZ3tfxKqog=;B<;~={>uTvj4T23&4d!DL-VuV#YNoPjFX3nJ_Uf<<
zt5Wx|07zl?8}OKaXTFht&4YsD_tNU_$#ZQ0eFd4*Lyy*mGsq;D6AaNvcNr!5HjpD`
zvo7Z^F!uaIHlJWS5f#nLr@G`v=n6$)K|wr$((O;m>z4r2bdJrI4Ip=r2$4`ns%}Ik
z9!v&e8W>n&j=gYtN|k_C>6w3N*2`KKX(O`|ZpNNQDt@&<POnv3cd96D2NDcRQPhCf
z4Yp!l$;`^%JYDoJJ}cB&ibQ(s9z8MG)b?Po#+HAuH&gI@sZ^pW31)DmS?nyLTd^$V
zRQ+){c_~}ImmivKx^3WLF*QwKK7*htT*HX$2n|N<jKL(Amf}0`%G)mZEgQX8*BJzi
z4>&HP-xizm{hxQ_grlK~QsEl;Y&F?Hjdq#4#GeCi_%ohO>BAwXO-s&;3=6ei?7&wV
zzhx@|hidh?N>#t;t@#-W$k2q9Ut*T#fQ)~FSV<_2JF5CtYyqp7Iv4Q(`9|05z<#tU
zyXVg^a{vSSF@SEc$lK-YBe*Z9EP<2pSD$7NowEongw`ER96U?P{%#p~f(s>1560Eq
zirEI#MpALRPEjm>3?_h%XAi9?A9RcDi1neQlA|7v5e|qbIOyTKKF<BbZbhLc-u7le
z3Lg^wEO#m7IU8S+%cR5Cxjb{aLZuQB@b9(j+%0D;86oFy_8v*`XP+%i7exxidB%!|
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
WNSM9%luV`pUWU3RH_El0qy7)RKj>iq

literal 0
HcmV?d00001

diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
new file mode 100644
index 000000000..b7aae2dda
--- /dev/null
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -0,0 +1,942 @@
+Build System (CMake)
+********************
+
+.. include:: ../cmake-warning.rst
+
+.. include:: ../cmake-pending-features.rst
+
+This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components". :doc:`Documentation for the GNU Make based build system <build-system>` is also available
+
+Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system.
+
+
+Overview
+========
+
+An ESP-IDF project can be seen as an amalgamation of a number of components.
+For example, for a webserver that shows the current humidity, there could be:
+
+- The ESP32 base libraries (libc, ROM bindings, etc)
+- The WiFi drivers
+- A TCP/IP stack
+- The FreeRTOS operating system
+- A webserver
+- A driver for the humidity sensor
+- Main code tying it all together
+
+ESP-IDF makes these components explicit and configurable. To do that,
+when a project is compiled, the build system will look up all the
+components in the ESP-IDF directories, the project directories and
+(optionally) in additional custom component directories. It then
+allows the user to configure the ESP-IDF project using a a text-based
+menu system to customize each component. After the components in the
+project are configured, the build system will compile the project.
+
+Concepts
+--------
+
+- A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting elements such as a partition table, data/filesystem partitions, and a bootloader.
+
+- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
+
+- An "app" is an executable which is built by ESP-IDF. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
+
+- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
+
+Some things are not part of the project:
+
+- "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
+
+- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
+
+Using the Build System
+======================
+
+.. _idf.py:
+
+idf.py
+------
+
+The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
+
+- CMake_, which configures the project to be built
+- A command line build tool (either Ninja_ build or `GNU Make`)
+- `esptool.py`_ for flashing ESP32.
+
+The :ref:`getting started guide <get-started-configure-cmake>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
+
+``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
+
+Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
+
+- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
+- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
+
+  - Create the build directory if needed. The sub-directory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
+  - Run CMake_ as necessary to configure the project and generate build files for the main build tool.
+  - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
+
+  Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
+- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
+- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
+- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
+- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
+- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`/get-started/idf-monitor` for more details about using the monitor.
+
+Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
+
+.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
+
+Advanced Commands
+^^^^^^^^^^^^^^^^^
+
+- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
+- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
+- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
+- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
+
+The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
+
+Using CMake Directly
+--------------------
+
+:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
+
+.. highlight:: bash
+
+When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt)::
+
+  mkdir -p build
+  cd build
+  cmake .. -G Ninja   # or 'Unix Makefiles'
+  ninja
+
+In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: running ``ninja`` actually builds the project.
+
+It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguration.
+
+If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` sub-commands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
+
+.. note::
+   If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
+
+Using CMake in an IDE
+---------------------
+
+You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
+
+When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
+
+For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_.
+
+.. setting-python-interpreter:
+
+Setting the Python Interpreter
+------------------------------
+
+Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems.
+
+If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command.
+
+If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter.
+
+If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter.
+
+To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version.
+
+.. _example-project-structure:
+
+Example Project
+===============
+
+.. highlight:: none
+
+An example project directory tree might look like this::
+
+    - myProject/
+                 - CMakeLists.txt
+                 - sdkconfig
+                 - components/ - component1/ - CMakeLists.txt
+                                             - Kconfig
+                                             - src1.c
+                               - component2/ - CMakeLists.txt
+                                             - Kconfig
+                                             - src1.c
+                                             - include/ - component2.h
+                 - main/       - src1.c
+                               - src2.c
+
+                 - build/
+
+This example "myProject" contains the following elements:
+
+- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
+  implements the rest of the build system. Finally, it sets the project name and defines the project.
+
+- "sdkconfig" project configuration file. This file is created/updated when ``idf.py menuconfig`` runs, and holds configuration for all of the components in the project (including ESP-IDF itself). The "sdkconfig" file may or may not be added to the source control system of the project.
+
+- Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
+
+- "main" directory is a special "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
+
+- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
+
+Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
+to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
+
+Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
+
+Project CMakeLists File
+=======================
+
+Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
+
+Minimal Example CMakeLists
+--------------------------
+
+.. highlight:: cmake
+
+Minimal project::
+
+      cmake_minimum_required(VERSION 3.5)
+
+      set(MAIN_SRCS main/src1.c main/src2.c)
+
+      include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+      project(myProject)
+
+
+.. _project-mandatory-parts:
+
+Mandatory Parts
+---------------
+
+The inclusion of these four lines, in the order shown above, is necessary for every project:
+
+- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
+- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" sub-directory, but this structure is encouraged.
+
+  It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
+
+  ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
+- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
+- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
+
+
+Optional Project Variables
+--------------------------
+
+These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
+
+- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
+- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
+- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list can be very short.
+- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically added to every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this variable is set to the minimal set of core "system" components needed for any ESP-IDF project. Usually, you would not change this variable in your project.
+
+Any paths in these variables can be absolute paths, or set relative to the project directory.
+
+To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
+
+.. _component-directories-cmake:
+
+Component CMakeLists Files
+==========================
+
+Each project contains one or more components. Components can be part of ESP-IDF, part of the project's own components directory, or added from custom component directories (:ref:`see above <component-directories-cmake>`).
+
+A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
+
+Searching for Components
+------------------------
+
+The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose sub-directories are components.
+
+When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
+
+Multiple components with the same name
+--------------------------------------
+
+When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
+contain component sub-directories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components
+with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
+If used in this way, the ESP-IDF directory itself can remain untouched.
+
+Minimal Component CMakeLists
+----------------------------
+
+.. highlight:: cmake
+
+The minimal component ``CMakeLists.txt`` file is as follows::
+
+  set(COMPONENT_SRCDIRS ".")
+  set(COMPONENT_ADD_INCLUDEDIRS "include")
+  register_component()
+
+- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
+- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for any component which requires this component, and also the main source files.
+- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if function <cmake if_>`_ or similar), this component will not be part of the build.
+
+Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
+
+See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
+
+.. _component variables:
+
+Preset Component Variables
+--------------------------
+
+The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
+
+- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
+- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
+
+The following variables are set at the project level, but available for use in component CMakeLists:
+
+- ``PROJECT_NAME``: Name of the project, as set in project Makefile
+- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
+- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
+- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
+- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
+
+If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
+
+- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for
+  all other components which require this one. If an include directory is only needed to compile this specific component,
+  add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
+- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If this component has a header file in a ``COMPONENT_ADD_INCLUDEDIRS`` directory that includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
+
+  The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
+
+  If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
+
+  See `Component Requirements`_ for more details.
+
+Optional Component-Specific Variables
+-------------------------------------
+
+The following variables can be set inside ``component.mk`` to control the build of that component:
+
+- ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
+  the component directory, which will be added to the include search
+  path for this component's source files only.
+- ``COMPONENT_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements`_ for more details.
+- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``,
+  ``*.c``, ``*.S``). Set this to specify a list of directories which contain source files.
+- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
+  If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``.
+- ``COMPONENT_SRCEXCLUDE``: Paths to source files to exclude from component. Can be set in conjunction with ``COMPONENT_SRCDIRS`` if there is a directory with a large number of source files to include in the component but one or more source files which should not be. Paths can be specified relative to the component directory or absolute.
+
+Controlling Component Compilation
+---------------------------------
+
+.. highlight:: cmake
+
+To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
+
+  component_compile_options(-Wno-unused-variable)
+
+This is a wrapper around the CMake `target_compile_options`_ command.
+
+To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
+
+    set_source_files_properties(mysrc.c
+        PROPERTIES COMPILE_FLAGS
+        -Wno-unused-variable
+    )
+
+This can be useful if there is upstream code that emits warnings.
+
+When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
+
+.. _component-configuration-cmake:
+
+Component Configuration
+=======================
+
+Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains
+configuration settings to add to the configuration menu for this component.
+
+These settings are found under the "Component Settings" menu when menuconfig is run.
+
+To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with ESP-IDF.
+
+For an example, see `Adding conditional configuration`_.
+
+Preprocessor Definitions
+========================
+
+The ESP-IDF build system adds the following C preprocessor definitions on the command line:
+
+- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
+- ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
+
+Component Requirements
+======================
+
+When compiling each component, the ESP-IDF build system recursively evaluates its components.
+
+Each component's source file is compiled with these include path directories:
+
+- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
+- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
+- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
+
+When writing a component
+------------------------
+
+- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
+- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
+- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
+- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
+- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
+
+When creating a project
+-----------------------
+
+- By default, every component is included in the build.
+- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
+  - Components mentioned explicitly in ``COMPONENTS``.
+  - Those components' requirements (evaluated recursively).
+  - The "common" components that every component depends on.
+- Setting ``COMPONENTS`` to the minimal list of required components can significantly reduce compile times.
+- When compiling the project's source files (``MAIN_SRCS``), the public header directories (``COMPONENT_ADD_INCLUDEDIRS`` list) of all components included in the build are available.
+
+.. _component-requirements-implementation:
+
+Requirements in the build system implementation
+-----------------------------------------------
+
+- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
+- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
+- Configuration is then evaluated for the components included in the build.
+- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
+
+Build Process Internals
+=======================
+
+For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`_.
+
+project.cmake contents
+----------------------
+
+When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environment.
+
+It also defines an overridden custom version of the built-in CMake_ ``project`` function. This function is overridden to add all of the ESP-IDF specific project functionality.
+
+project function
+----------------
+
+The custom ``project()`` function performs the following steps:
+
+- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above<component-requirements-implementation>`).
+- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
+- Loads the project configuration from the ``sdkconfig`` file and generates a ``sdkconfig.cmake`` file and a ``sdkconfig.h`` header. These define configuration values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to re-generate these files and re-configure the project.
+- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
+- Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
+- Load the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
+- Include ``project_include.cmake`` files from any components which have them.
+- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the CMake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
+- Add the final app executable to the build.
+- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
+
+Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
+
+Debugging CMake
+---------------
+
+Some tips for debugging the ESP-IDF CMake-based build system:
+
+- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
+- Running ``cmake -DDEBUG=1`` will produce more verbose diagnostic output from the IDF build system.
+- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
+
+.. _warn-undefined-variables-cmake:
+
+Warning On Undefined Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
+
+If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
+
+Overriding Parts of the Project
+-------------------------------
+
+project_include.cmake
+^^^^^^^^^^^^^^^^^^^^^
+
+For components that have build requirements which must be evaluated before any component CMakeLists
+files are evaluated, you can create a file called ``project_include.cmake`` in the
+component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
+
+``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
+
+Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
+
+Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
+
+KConfig.projbuild
+^^^^^^^^^^^^^^^^^
+
+This is an equivalent to ``project_include.cmake`` for :ref:`component-configuration-cmake` KConfig files. If you want to include
+configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
+
+Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for :ref:`component-configuration-cmake`.
+
+
+Configuration-Only Components
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
+
+If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
+
+Example Component CMakeLists
+============================
+
+Because the build environment tries to set reasonable defaults that will work most
+of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
+
+Here are some more advanced examples of component CMakeLists files.
+
+Adding conditional configuration
+--------------------------------
+
+The configuration system can be used to conditionally compile some files
+depending on the options selected in the project configuration.
+
+.. highlight:: none
+
+``Kconfig``::
+
+    config FOO_ENABLE_BAR
+        bool "Enable the BAR feature."
+        help
+            This enables the BAR feature of the FOO component.
+
+``CMakeLists.txt``::
+
+    set(COMPONENT_SRCS "foo.c" "more_foo.c")
+
+    if(CONFIG_FOO_ENABLE_BAR)
+        list(APPEND COMPONENT_SRCS "bar.c")
+    endif(CONFIG_FOO_ENABLE_BAR)
+
+This example makes use of the CMake `if function <cmake if_>`_ and `list APPEND <cmake list_>`_ function.
+
+This can also be used to select or stub out an implementation, as such:
+
+``Kconfig``::
+
+    config ENABLE_LCD_OUTPUT
+        bool "Enable LCD output."
+        help
+            Select this if your board has a LCD.
+
+    config ENABLE_LCD_CONSOLE
+        bool "Output console text to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output debugging output to the lcd
+
+    config ENABLE_LCD_PLOT
+        bool "Output temperature plots to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output temperature plots
+
+.. highlight:: cmake
+
+``CMakeLists.txt``::
+
+    if(CONFIG_ENABLE_LCD_OUTPUT)
+       set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
+    else()
+       set(COMPONENT_SRCS lcd-dummy.c)
+    endif()
+
+    # We need font if either console or plot is enabled
+    if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_ENABLE_LCD_PLOT)
+      list(APPEND COMPONENT_SRCS "font.c")
+    endif()
+
+
+Source Code Generation
+----------------------
+
+Some components will have a situation where a source file isn't
+supplied with the component itself but has to be generated from
+another file. Say our component has a header file that consists of the
+converted binary data of a BMP file, converted using a hypothetical
+tool called bmp2h. The header file is then included in as C source
+file called graphics_lib.c::
+
+    add_custom_command(OUTPUT logo.h
+         COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
+         DEPENDS ${COMPONENT_PATH}/logo.bmp
+         VERBATIM)
+
+    add_custom_target(logo DEPENDS logo.h)
+    add_dependencies(${COMPONENT_NAME} logo)
+
+    set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
+         ADDITIONAL_MAKE_CLEAN_FILES logo.h)
+
+This answer is adapted from the `CMake FAQ entry <cmake faq generated files_>`_, which contains some other examples that will also work with ESP-IDF builds.
+
+In this example, logo.h will be generated in the
+current directory (the build directory) while logo.bmp comes with the
+component and resides under the component path. Because logo.h is a
+generated file, it should be cleaned when the project is cleaned. For this reason
+it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
+
+.. note::
+
+   If generating files as part of the project CMakeLists.txt file, not a component CMakeLists.txt, then use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
+
+If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
+the two components, to ensure that the component source files were always compiled in the correct order.
+
+Embedding Binary Data
+---------------------
+
+Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
+
+You can set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving space-delimited names of the files to embed::
+
+  set(COMPONENT_EMBED_FILES server_root_cert.der)
+
+Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string::
+
+  set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
+
+.. highlight:: c
+
+The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
+
+  extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
+  extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
+
+The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
+
+.. highlight:: cmake
+
+To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
+
+  target_add_binary_data(myproject.elf "main/data.bin" TEXT)
+
+Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
+
+For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
+
+.. _component-build-full-override:
+
+Fully Overriding The Component Build Process
+--------------------------------------------
+
+.. highlight:: cmake
+
+Obviously, there are cases where all these recipes are insufficient for a
+certain component, for example when the component is basically a wrapper
+around another third-party component not originally intended to be
+compiled under this build system. In that case, it's possible to forego
+the ESP-IDF build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
+
+  # External build process for quirc, runs in source dir and
+  # produces libquirc.a
+  externalproject_add(quirc_build
+      PREFIX ${COMPONENT_PATH}
+      SOURCE_DIR ${COMPONENT_PATH}/quirc
+      CONFIGURE_COMMAND ""
+      BUILD_IN_SOURCE 1
+      BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
+      INSTALL_COMMAND ""
+      )
+
+   # Add libquirc.a to the build process
+   #
+   add_library(quirc STATIC IMPORTED GLOBAL)
+   add_dependencies(quirc quirc_build)
+
+   set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
+        ${COMPONENT_PATH}/quirc/libquirc.a)
+   set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
+        ${COMPONENT_PATH}/quirc/lib)
+
+   set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
+        "${COMPONENT_PATH}/quirc/libquirc.a")
+
+(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
+
+- ``externalproject_add`` defines an external build system.
+  
+  - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
+  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
+  - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
+
+- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
+- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
+
+.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
+
+ExternalProject dependencies, clean builds
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CMake has some unusual behaviour around external project builds:
+
+- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
+- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
+- Therefore, there are two alternative recommended ways to configure the external build command:
+
+    1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
+    2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
+
+The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
+
+.. _custom-sdkconfig-defaults-cmake:
+
+Custom sdkconfig defaults
+=========================
+
+For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the ESP-IDF defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
+
+To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
+
+
+Flash arguments
+===============
+
+There are some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
+
+After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
+
+- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
+- ``flash_app_args`` contains arguments to flash only the app.
+- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
+
+.. highlight:: bash
+
+You can pass any of these flasher argument files to ``esptool.py`` as follows::
+
+  python esptool.py --chip esp32 write_flash @build/flash_project_args
+
+Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
+
+The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
+
+Building the Bootloader
+=======================
+
+The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
+
+The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
+
+The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
+
+Writing Pure CMake Components
+=============================
+
+The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
+
+However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
+
+.. highlight:: cmake
+
+Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``::
+
+  add_library(json STATIC
+  cJSON/cJSON.c
+  cJSON/cJSON_Utils.c)
+
+  target_include_directories(json PUBLIC cJSON)
+
+- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
+- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
+- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
+
+
+File Globbing & Incremental Builds
+==================================
+
+.. highlight:: cmake
+
+The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
+
+  set(COMPONENT_SRCDIRS library platform)
+
+The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
+
+  set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
+
+CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
+
+The trade-off is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
+
+For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
+
+For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is the approach which CMake_ recommends.)
+
+For project components (not part of ESP-IDF), there are a few different options:
+
+- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes.
+- If some components are kept in a third git repository (not the project repository or ESP-IDF repository), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to automatically trigger re-runs of CMake when the Git revision changes.
+- If not using Git, remember to manually run ``idf.py reconfigure`` whenever a source file may change.
+- To avoid this problem entirely, use ``COMPONENT_SRCS`` to list all source files in project components.
+
+The best option will depend on your particular project and its users.
+
+Build System Metadata
+=====================
+
+For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
+
+- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
+- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
+- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
+- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
+- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
+- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs.
+
+JSON Configuration Server
+-------------------------
+
+.. highlight :: json
+
+A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
+
+You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator.
+
+The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``::
+
+  {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
+
+Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.)
+
+The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline::
+
+   {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
+
+The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes::
+
+   {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
+
+Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value.
+
+If the range of a config item changes, due to conditional range depending on another value, then this is also sent::
+
+   {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
+
+If invalid data is passed, an "error" field is present on the object::
+
+    {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
+
+By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent::
+
+    {"version": 1, "save": null }
+
+To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent::
+
+    {"version": 1, "load": null }
+
+The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname.
+
+The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started.
+
+Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command.
+
+.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited.
+
+.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run.
+
+.. _gnu-make-to-cmake:
+
+Migrating from ESP-IDF GNU Make System
+======================================
+
+Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
+
+Automatic Conversion Tool
+-------------------------
+
+.. highlight:: bash
+
+An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this::
+
+    $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir
+
+The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH.
+
+The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files.
+
+It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables.
+
+The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand.
+
+'main' is no longer a component
+-------------------------------
+
+In the GNU Make build system ``main`` is a component with a ``component.mk`` file like other components.
+
+Due to CMake requirements for building executables, ``main`` source files are now linked directly into the final binary. The source files in ``main`` must be listed in the ``MAIN_SRCS`` variable (see :ref:`project mandatory variables <project-mandatory-parts>` for more details). At least one source file has to be listed here (although it doesn't need to contain anything in particular).
+
+In general, it's better not to have too many source files in ``MAIN_SRCS``. If you find that you are adding many source files here, see if you can reorganize and group some into project components (see the :ref:`example project structure <example-project-structure>`, above).
+
+No Longer Available in CMake
+----------------------------
+
+Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
+
+- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
+- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component.
+- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
+- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
+- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
+- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``.
+- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repository.
+- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
+- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``.
+- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead.
+- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
+- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
+- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_.
+
+
+No Default Values
+-----------------
+
+The following variables no longer have default values:
+
+- ``COMPONENT_SRCDIRS``
+- ``COMPONENT_ADD_INCLUDEDIRS``
+
+No Longer Necessary
+-------------------
+
+It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
+
+
+.. _esp-idf-template: https://github.com/espressif/esp-idf-template
+.. _cmake: https://cmake.org
+.. _ninja: https://ninja-build.org
+.. _esptool.py: https://github.com/espressif/esptool/#readme
+.. _CMake v3.5 documentation: https://cmake.org/cmake/help/v3.5/index.html
+.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
+.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/project.html
+.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html
+.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html
+.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html
+.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html
+.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html
+.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
+.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
+.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
+.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
+.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
+.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
+.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
+.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
+.. _quirc: https://github.com/dlbeer/quirc
+.. _pyenv: https://github.com/pyenv/pyenv#README
+.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+
diff --git a/docs/en/api-guides/build-system.rst b/docs/en/api-guides/build-system.rst
index a5054fe63..e638a36d0 100644
--- a/docs/en/api-guides/build-system.rst
+++ b/docs/en/api-guides/build-system.rst
@@ -1,19 +1,17 @@
 Build System
 ************
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+This document explains the Espressif IoT Development Framework build system and the
+concept of "components"
 
-This document explains the implementation of the CMake-based ESP-IDF build system and the concept of "components".
+Read this document if you want to know how to organise a new ESP-IDF project.
 
-Read this document if you want to know how to organise and build a new ESP-IDF project or component using the CMake-based build system.
+We recommend using the esp-idf-template_ project as a starting point for your project.
 
-For information relating to the older GNU Make-based build system, see here:
+Using the Build System
+======================
 
-.. toctree::
-    :maxdepth: 1
-
-    gnu-make-build-system
+The esp-idf README file contains a description of how to use the build system to build your project.
 
 Overview
 ========
@@ -21,7 +19,7 @@ Overview
 An ESP-IDF project can be seen as an amalgamation of a number of components.
 For example, for a webserver that shows the current humidity, there could be:
 
-- The ESP32 base libraries (libc, ROM bindings, etc)
+- The ESP32 base libraries (libc, rom bindings etc)
 - The WiFi drivers
 - A TCP/IP stack
 - The FreeRTOS operating system
@@ -30,480 +28,425 @@ For example, for a webserver that shows the current humidity, there could be:
 - Main code tying it all together
 
 ESP-IDF makes these components explicit and configurable. To do that,
-when a project is compiled, the build system will look up all the
+when a project is compiled, the build environment will look up all the
 components in the ESP-IDF directories, the project directories and
 (optionally) in additional custom component directories. It then
 allows the user to configure the ESP-IDF project using a a text-based
 menu system to customize each component. After the components in the
-project are configured, the build system will compile the project.
+project are configured, the build process will compile the project.
 
 Concepts
 --------
 
 - A "project" is a directory that contains all the files and configuration to build a single "app" (executable), as well as additional supporting output such as a partition table, data/filesystem partitions, and a bootloader.
 
-- "Project configuration" is held in a single file called ``sdkconfig`` in the root directory of the project. This configuration file is modified via ``idf.py menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
+- "Project configuration" is held in a single file called sdkconfig in the root directory of the project. This configuration file is modified via ``make menuconfig`` to customise the configuration of the project. A single project contains exactly one project configuration.
 
 - An "app" is an executable which is built by esp-idf. A single project will usually build two apps - a "project app" (the main executable, ie your custom firmware) and a "bootloader app" (the initial bootloader program which launches the project app).
 
-- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by ESP-IDF itself, others may be sourced from other places.
+- "components" are modular pieces of standalone code which are compiled into static libraries (.a files) and linked into an app. Some are provided by esp-idf itself, others may be sourced from other places.
 
 Some things are not part of the project:
 
 - "ESP-IDF" is not part of the project. Instead it is standalone, and linked to the project via the ``IDF_PATH`` environment variable which holds the path of the ``esp-idf`` directory. This allows the IDF framework to be decoupled from your project.
 
-- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH.
+- The toolchain for compilation is not part of the project. The toolchain should be installed in the system command line PATH, or the path to the toolchain can be set as part of the compiler prefix in the project configuration.
 
-Using the Build System
-======================
-
-.. _idf.py:
-
-idf.py
-------
-
-The ``idf.py`` command line tool provides a front-end for easily managing your project builds. It manages the following tools:
-
-- CMake_, which configures the project to be built
-- A command line build tool (either Ninja_ build or `GNU Make`)
-- `esptool.py`_ for flashing ESP32.
-
-The :ref:`getting started guide <get-started-configure>` contains a brief introduction to how to set up ``idf.py`` to configure, build, and flash projects.
-
-``idf.py`` should be run in an ESP-IDF "project" directory, ie one containing a ``CMakeLists.txt`` file. Older style projects with a Makefile will not work with ``idf.py``.
-
-Type ``idf.py --help`` for a full list of commands. Here are a summary of the most useful ones:
-
-- ``idf.py menuconfig`` runs the "menuconfig" tool to configure the project.
-- ``idf.py build`` will build the project found in the current directory. This can involve multiple steps:
-  - Create the build directory if needed. The subdirectory ``build`` is used to hold build output, although this can be changed with the ``-B`` option.
-  - Run CMake_ as necessary to configure the project and generate build files for the main build tool.
-  - Run the main build tool (Ninja_ or `GNU Make`). By default, the build tool is automatically detected but it can be explicitly set by passing the ``-G`` option to ``idf.py``.
-  Building is incremental so if no source files or configuration has changed since the last build, nothing will be done.
-- ``idf.py clean`` will "clean" the project by deleting build output files from the build directory, forcing a "full rebuild" the next time the project is built. Cleaning doesn't delete CMake configuration output and some other files.
-- ``idf.py fullclean`` will delete the entire "build" directory contents. This includes all CMake configuration output. The next time the project is built, CMake will configure it from scratch. Note that this option recursively deletes *all* files in the build directory, so use with care. Project configuration is not deleted.
-- ``idf.py reconfigure`` re-runs CMake_ even if it doesn't seem to need re-running. This isn't necessary during normal usage, but can be useful after adding/removing files from the source tree.
-- ``idf.py flash`` will automatically build the project if necessary, and then flash it to an ESP32. The ``-p`` and ``-b`` options can be used to set serial port name and flasher baud rate, respectively.
-- ``idf.py monitor`` will display serial output from the ESP32. The ``-p`` option can be used to set the serial port name. Type ``Ctrl-]`` to exit the monitor. See :doc:`/get-started/idf-monitor` for more details about using the monitor.
-
-Multiple ``idf.py`` commands can be combined into one. For example, ``idf.py -p COM4 clean flash monitor`` will clean the source tree, then build the project and flash it to the ESP32 before running the serial monitor.
-
-.. note:: The environment variables ``ESPPORT`` and ``ESPBAUD`` can be used to set default values for the ``-p`` and ``-b`` options, respectively. Providing these options on the command line overrides the default.
-
-Advanced Commands
-^^^^^^^^^^^^^^^^^
-
-- ``idf.py app``, ``idf.py bootloader``, ``idf.py partition_table`` can be used to build only the app, bootloader, or partition table from the project as applicable.
-- There are matching commands ``idf.py app-flash``, etc. to flash only that single part of the project to the ESP32.
-- ``idf.py -p PORT erase_flash`` will use esptool.py to erase the ESP32's entire flash chip.
-- ``idf.py size`` prints some size information about the app. ``size-components`` and ``size-files`` are similar commands which print more detailed per-component or per-source-file information, respectively.
-
-The order of multiple ``idf.py`` commands on the same invocation is not important, they will automatically be executed in the correct order for everything to take effect (ie building before flashing, erasing before flashing, etc.).
-
-Using CMake Directly
---------------------
-
-:ref:`idf.py` is a wrapper around CMake_ for convenience. However, you can also invoke CMake directly if you prefer.
-
-.. highlight:: bash
-
-When ``idf.py`` does something, it prints each command that it runs for easy reference. For example, the ``idf.py build`` command is the same as running these commands in a bash shell (or similar commands for Windows Command Prompt)::
-
-  mkdir -p build
-  cd build
-  cmake .. -G Ninja   # or 'GNU Make'
-  ninja
-
-In the above list, the ``cmake`` command configures the project and generates build files for use with the final build tool. In this case the final build tool is Ninja_: runnning ``ninja`` actually builds the project.
-
-It's not necessary to run ``cmake`` more than once. After the first build, you only need to run ``ninja`` each time. ``ninja`` will automatically re-invoke ``cmake`` if the project needs reconfiguring.
-
-If using CMake with ``ninja`` or ``make``, there are also targets for more of the ``idf.py`` subcommands - for example running ``make menuconfig`` or ``ninja menuconfig`` in the build directory will work the same as ``idf.py menuconfig``.
-
-.. note::
-   If you're already familiar with CMake_, you may find the ESP-IDF CMake-based build system unusual because it wraps a lot of CMake's functionality to reduce boilerplate. See `writing pure CMake components`_ for some information about writing more "CMake style" components.
-
-Using CMake in an IDE
----------------------
-
-You can also use an IDE with CMake integration. The IDE will want to know the path to the project's ``CMakeLists.txt`` file. IDEs with CMake integration often provide their own build tools (CMake calls these "generators") to build the source files as part of the IDE.
-
-When adding custom non-build steps like "flash" to the IDE, it is recommended to execute ``idf.py`` for these "special" commands.
-
-For more detailed information about integrating ESP-IDF with CMake into an IDE, see `Build System Metadata`_.
-
-.. setting-python-interpreter:
-
-Setting the Python Interpreter
-------------------------------
-
-Currently, ESP-IDF only works with Python 2.7. If you have a system where the default ``python`` interpreter is Python 3.x, this can lead to problems.
-
-If using ``idf.py``, running ``idf.py`` as ``python2 $IDF_PATH/tools/idf.py ...`` will work around this issue (``idf.py`` will tell other Python processes to use the same Python interpreter). You can set up a shell alias or another script to simplify the command.
-
-If using CMake directly, running ``cmake -D PYTHON=python2 ...`` will cause CMake to override the default Python interpreter.
-
-If using an IDE with CMake, setting the ``PYTHON`` value as a CMake cache override in the IDE UI will override the default Python interpreter.
-
-To manage the Python version more generally via the command line, check out the tools pyenv_ or virtualenv_. These let you change the default python version.
-
-.. _example-project-structure:
 
 Example Project
-===============
-
-.. highlight:: none
+---------------
 
 An example project directory tree might look like this::
 
     - myProject/
-                 - CMakeLists.txt
+                 - Makefile
                  - sdkconfig
-                 - components/ - component1/ - CMakeLists.txt
+                 - components/ - component1/ - component.mk
                                              - Kconfig
                                              - src1.c
-                               - component2/ - CMakeLists.txt
+                               - component2/ - component.mk
                                              - Kconfig
                                              - src1.c
                                              - include/ - component2.h
                  - main/       - src1.c
                                - src2.c
+                               - component.mk
 
                  - build/
 
 This example "myProject" contains the following elements:
 
-- A top-level project CMakeLists.txt file. This is the primary file which CMake uses to learn how to build the project. The project CMakeLists.txt file sets the ``MAIN_SRCS`` variable which lists all of the source files in the "main" directory (part of this project's executable). It may set other project-wide CMake variables, as well. Then it includes the file :idf_file:`/tools/cmake/project.cmake` which
-  implements the rest of the build system. Finally, it sets the project name and defines the project.
+- A top-level project Makefile. This Makefile set the ``PROJECT_NAME`` variable and (optionally) defines
+  other project-wide make variables. It includes the core ``$(IDF_PATH)/make/project.mk`` makefile which
+  implements the rest of the ESP-IDF build system.
 
 - "sdkconfig" project configuration file. This file is created/updated when "make menuconfig" runs, and holds configuration for all of the components in the project (including esp-idf itself). The "sdkconfig" file may or may not be added to the source control system of the project.
 
 - Optional "components" directory contains components that are part of the project. A project does not have to contain custom components of this kind, but it can be useful for structuring reusable code or including third party components that aren't part of ESP-IDF.
 
-- "main" directory is a special "by convention" directory that contains source code for the project executable itself. These source files are listed in the project's CMakeLists file. You don't need to name this directory "main", but we recommend you follow this convention. If you have a lot of source files in your project, we recommend grouping most into components instead of putting them all in "main".
+- "main" directory is a special "pseudo-component" that contains source code for the project itself. "main" is a default name, the Makefile variable ``COMPONENT_DIRS`` includes this component but you can modify this variable (or set ``EXTRA_COMPONENT_DIRS``) to look for components in other places.
 
-- "build" directory is where build output is created. This directory is created by ``idf.py`` if it doesn't already exist. CMake configures the project and generates interim build files in this directory. Then, after the main build process is run, this directory will also contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
+- "build" directory is where build output is created. After the make process is run, this directory will contain interim object files and libraries as well as final binary output files. This directory is usually not added to source control or distributed with the project source code.
 
-Component directories each contain a component ``CMakeLists.txt`` file. This file contains variable definitions
-to control the build process of the component, and its integration into the overall project. See `Component CMakeLists Files`_ for more details.
+Component directories contain a component makefile - ``component.mk``. This may contain variable definitions
+to control the build process of the component, and its integration into the overall project. See `Component Makefiles`_ for more details.
 
-Each component may also include a ``Kconfig`` file defining the `component configuration`_ options that can be set via ``menuconfig``. Some components may also include ``Kconfig.projbuild`` and ``project_include.cmake`` files, which are special files for `overriding parts of the project`_.
+Each component may also include a ``Kconfig`` file defining the `component configuration` options that can be set via the project configuration. Some components may also include ``Kconfig.projbuild`` and ``Makefile.projbuild`` files, which are special files for `overriding parts of the project`.
 
-Project CMakeLists File
-=======================
+Project Makefiles
+-----------------
 
-Each project has a single top-level ``CMakeLists.txt`` file that contains build settings for the entire project. By default, the project CMakeLists can be quite minimal.
+Each project has a single Makefile that contains build settings for the entire project. By default, the project Makefile can be quite minimal.
 
-Minimal Example CMakeLists
---------------------------
+Minimal Example Makefile
+^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. highlight:: cmake
+::
 
-Minimal project::
-
-      cmake_minimum_required(VERSION 3.5)
-
-      set(MAIN_SRCS main/src1.c main/src2.c)
-
-      include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-      project(myProject)
+   PROJECT_NAME := myProject
+   
+   include $(IDF_PATH)/make/project.mk
 
 
-.. _project-mandatory-parts:
-
-Mandatory Parts
----------------
-
-The inclusion of these four lines, in the order shown above, is necessary for every project:
-
-- ``cmake_minimum_required(VERSION 3.5)`` tells CMake what version is required to build the project. ESP-IDF is designed to work with CMake 3.5 or newer. This line must be the first line in the CMakeLists.txt file.
-- ``set(MAIN_SRCS xxx)`` sets a variable - ``MAIN_SRCS`` to be a list of the "main" source files in the project. Paths are relative to the CMakeLists. They don't specifically need to be under the "main" subdirectory, but this structure is encouraged.
-
-  It is *strongly recommended not to add a lot of files to the MAIN_SRCS list*. If you have a lot of source files then it recommended to organise them functionally into individual components under the project "components" directory. This will make your project more maintainable, reusable, and easier to configure. Components are further explained below.
-
-   ``MAIN_SRCS`` must name at least one source file (although that file doesn't need to necessarily include an ``app_main()`` function or anything else).
-- ``include($ENV{IDF_PATH}/tools/cmake/project.cmake)`` pulls in the rest of the CMake functionality to configure the project, discover all the components, etc.
-- ``project(myProject)`` creates the project itself, and specifies the project name. The project name is used for the final binary output files of the app - ie ``myProject.elf``, ``myProject.bin``. Only one project can be defined per CMakeLists file.
+Mandatory Project Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+- ``PROJECT_NAME``: Name of the project. Binary output files will use this name - ie myProject.bin, myProject.elf.
 
 Optional Project Variables
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-These variables all have default values that can be overridden for custom behaviour. Look in :idf_file:`/tools/cmake/project.cmake` for all of the implementation details.
+These variables all have default values that can be overridden for custom behaviour. Look in ``make/project.mk`` for all of the implementation details.
 
-- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `${IDF_PATH}/components`, `${PROJECT_PATH}/components`, and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
-- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components. Paths can be relative to the project directory, or absolute.
-- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the ``COMPONENT_DIRS`` directories. Use this variable to "trim down" the project for faster build times. Note that any component which "requires" another component via ``COMPONENT_REQUIRES`` will automatically have it added to this list, so the ``COMPONENTS`` list can be very short.
-- ``COMPONENT_REQUIRES_COMMON``: A list of components that every component requires. These components are automatically added to every component's ``COMPONENT_PRIV_REQUIRES`` list and also the project's ``COMPONENTS`` list. By default, this variable is set to the minimal set of core "system" components needed for any ESP-IDF project. Usually, you would not change this variable in your project.
+- ``PROJECT_PATH``: Top-level project directory. Defaults to the directory containing the Makefile. Many other project variables are based on this variable. The project path cannot contain spaces.
+- ``BUILD_DIR_BASE``: The build directory for all objects/libraries/binaries. Defaults to ``$(PROJECT_PATH)/build``.
+- ``COMPONENT_DIRS``: Directories to search for components. Defaults to `$(IDF_PATH)/components`, `$(PROJECT_PATH)/components`, ``$(PROJECT_PATH)/main`` and ``EXTRA_COMPONENT_DIRS``. Override this variable if you don't want to search for components in these places.
+- ``EXTRA_COMPONENT_DIRS``: Optional list of additional directories to search for components.
+- ``COMPONENTS``: A list of component names to build into the project. Defaults to all components found in the COMPONENT_DIRS directories.
+- ``EXCLUDE_COMPONENTS``: Optional list of component names to exclude during the build process. Note that this decreases build time, but not binary size.
 
-Any paths in these variables can be absolute paths, or set relative to the project directory.
+Any paths in these Makefile variables should be absolute paths. You can convert relative paths using ``$(PROJECT_PATH)/xxx``, ``$(IDF_PATH)/xxx``, or use the Make function ``$(abspath xxx)``.
 
-To set these variables, use the `cmake set command <cmake set_>`_ ie ``set(VARIABLE "VALUE")``. The ``set()`` commands should be placed after the ``cmake_minimum(...)`` line but before the ``include(...)`` line.
+These variables should all be set before the line ``include $(IDF_PATH)/make/project.mk`` in the Makefile.
 
-Component CMakeLists Files
-==========================
+Component Makefiles
+-------------------
 
-Each project contains one or more components. Components can be part of esp-idf, part of the project's own components directory, or added from custom component directories (see above).
+Each project contains one or more components, which can either be part of esp-idf or added from other component directories.
 
-A component is any directory in the ``COMPONENT_DIRS`` list which contains a ``CMakeLists.txt`` file.
+A component is any directory that contains a ``component.mk`` file.
 
 Searching for Components
 ------------------------
 
-The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `CMakeLists.txt` file), or they can be top-level directories whose subdirectories are components.
+The list of directories in ``COMPONENT_DIRS`` is searched for the project's components. Directories in this list can either be components themselves (ie they contain a `component.mk` file), or they can be top-level directories whose subdirectories are components.
 
-When CMake runs to configure the project, it logs the components included in the build. This list can be useful for debugging the inclusion/exclusion of certain components.
+Running the ``make list-components`` target dumps many of these variables and can help debug the discovery of component directories.
 
 Multiple components with the same name
---------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When ESP-IDF is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means ESP-IDF's internal components first, then the project's components, and finally any components set in ``EXTRA_COMPONENT_DIRS``. If two or more of these directories
-contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding ESP-IDF components
-with a modified version by copying that component from the ESP-IDF components directory to the project components directory and then modifying it there.
-If used in this way, the ESP-IDF directory itself can remain untouched.
+When esp-idf is collecting all the components to compile, it will do this in the order specified by ``COMPONENT_DIRS``; by default, this means the 
+idf components first, the project components second and optionally the components in ``EXTRA_COMPONENT_DIRS`` last. If two or more of these directories
+contain component subdirectories with the same name, the component in the last place searched is used. This allows, for example, overriding esp-idf components 
+with a modified version by simply copying the component from the esp-idf component directory to the project component tree and then modifying it there. 
+If used in this way, the esp-idf directory itself can remain untouched.
 
-Minimal Component CMakeLists
-----------------------------
+Minimal Component Makefile
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. highlight:: cmake
+The minimal ``component.mk`` file is an empty file(!). If the file is empty, the default component behaviour is set:
 
-The minimal component ``CMakeLists.txt`` file is as follows::
+- All source files in the same directory as the makefile (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) will be compiled into the component library
+- A sub-directory "include" will be added to the global include search path for all other components.
+- The component library will be linked into the project app.
 
-  set(COMPONENT_SRCDIRS ".")
-  set(COMPONENT_ADD_INCLUDEDIRS "include")
-  register_component()
+See `example component makefiles`_ for more complete component makefile examples.
 
-- ``COMPONENT_SRCDIRS`` is a (space-separated) list of directories to search for source files. Source files (``*.c``, ``*.cpp``, ``*.cc``, ``*.S``) in these directories will be compiled into the component library.
-- ``COMPONENT_ADD_INCLUDEDIRS`` is a (space-separated) list of directories to add to the global include search path for any component which requires this component, and also the main source files.
-- ``register_component()`` is required to add the component (using the variables set above) to the build. A library with the name of the component will be built and linked into the final app. If this step is skipped (perhaps due to use of a CMake `if function <cmake if_>`_ or similar), this component will not be part of the build.
+Note that there is a difference between an empty ``component.mk`` file (which invokes default component build behaviour) and no ``component.mk`` file (which means no default component build behaviour will occur.) It is possible for a component to have no `component.mk` file, if it only contains other files which influence the project configuration or build process.
 
-Directories are usually specified relative to the ``CMakeLists.txt`` file itself, although they can be absolute.
-
-See `example component CMakeLists`_ for more complete component ``CMakeLists.txt`` examples.
-
-.. _component variables:
+.. component variables:
 
 Preset Component Variables
---------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The following component-specific variables are available for use inside component CMakeLists, but should not be modified:
+The following component-specific variables are available for use inside ``component.mk``, but should not be modified:
 
-- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces. This is the same as the ``CMAKE_CURRENT_SOURCE_DIR`` variable.
-- ``COMPONENT_NAME``: Name of the component. Same as the name of the component directory.
+- ``COMPONENT_PATH``: The component directory. Evaluates to the absolute path of the directory containing ``component.mk``. The component path cannot contain spaces.
+- ``COMPONENT_NAME``: Name of the component. Defaults to the name of the component directory.
+- ``COMPONENT_BUILD_DIR``: The component build directory. Evaluates to the absolute path of a directory inside `$(BUILD_DIR_BASE)` where this component's source files are to be built. This is also the Current Working Directory any time the component is being built, so relative paths in make targets, etc. will be relative to this directory.
+- ``COMPONENT_LIBRARY``: Name of the static library file (relative to the component build directory) that will be built for this component. Defaults to ``$(COMPONENT_NAME).a``.
 
-The following variables are set at the project level, but available for use in component CMakeLists:
+The following variables are set at the project level, but exported for use in the component build:
 
 - ``PROJECT_NAME``: Name of the project, as set in project Makefile
-- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile. Same as the ``CMAKE_SOURCE_DIR`` variable.
-- ``COMPONENTS``: Names of all components that are included in this build, formatted as a semicolon-delimited CMake list.
-- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``. :doc:`More information here </api-reference/kconfig>`.
-- ``IDF_VER``: Git version of ESP-IDF (produced by ``git describe``)
+- ``PROJECT_PATH``: Absolute path of the project directory containing the project Makefile.
+- ``COMPONENTS``: Name of all components that are included in this build.
+- ``CONFIG_*``: Each value in the project configuration has a corresponding variable available in make. All names begin with ``CONFIG_``.
+- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain.
+- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain.
+- ``IDF_VER``: ESP-IDF version, retrieved from either ``$(IDF_PATH)/version.txt`` file (if present) else using git command ``git describe``. Recommended format here is single liner that specifies major IDF release version, e.g. ``v2.0`` for a tagged release or ``v2.0-275-g0efaa4f`` for an arbitrary commit. Application can make use of this by calling :cpp:func:`esp_get_idf_version`.
 
-If you modify any of these variables inside ``CMakeLists.txt`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
+If you modify any of these variables inside ``component.mk`` then this will not prevent other components from building but it may make your component hard to build and/or debug.
 
-- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component directory, which will be added to the include search path for
-  all other components which require this one. If an include directory is only needed to compile this specific component,
-  add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
-- ``COMPONENT_REQUIRES`` is a (space-separated) list of components that are required to include this project's header files into other components. If this component has a header file in a ``COMPONENT_ADD_INCLUDEDIRS`` directory that includes a header from another component, that component should be listed in ``COMPONENT_REQUIRES``. Requirements are recursive.
+Optional Project-Wide Component Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-  The ``COMPONENT_REQUIRES`` list can be empty because some very common components (like newlib for libc, freertos for RTOS functions, etc) are always required by all components. This list is found in the project-level variable ``COMPONENT_REQUIRES_COMMON``.
+The following variables can be set inside ``component.mk`` to control build settings across the entire project:
 
-  If a component only requires another component's headers to compile its source files (not for including this component's headers), then these components should be listed in ``COMPONENT_PRIV_REQUIRES`` instead.
+- ``COMPONENT_ADD_INCLUDEDIRS``: Paths, relative to the component
+  directory, which will be added to the include search path for
+  all components in the project. Defaults to ``include`` if not overridden. If an include directory is only needed to compile
+  this specific component, add it to ``COMPONENT_PRIV_INCLUDEDIRS`` instead.
+- ``COMPONENT_ADD_LDFLAGS``: Add linker arguments to the LDFLAGS for
+  the app executable. Defaults to ``-l$(COMPONENT_NAME)``.  If
+  adding pre-compiled libraries to this directory, add them as
+  absolute paths - ie $(COMPONENT_PATH)/libwhatever.a
+- ``COMPONENT_DEPENDS``: Optional list of component names that should
+  be compiled before this component. This is not necessary for
+  link-time dependencies, because all component include directories
+  are available at all times. It is necessary if one component
+  generates an include file which you then want to include in another
+  component. Most components do not need to set this variable.
+- ``COMPONENT_ADD_LINKER_DEPS``: Optional list of component-relative paths
+  to files which should trigger a re-link of the ELF file if they change.
+  Typically used for linker script files and binary libraries. Most components do
+  not need to set this variable.
+
+The following variable only works for components that are part of esp-idf itself:
+
+- ``COMPONENT_SUBMODULES``: Optional list of git submodule paths
+  (relative to COMPONENT_PATH) used by the component. These will be
+  checked (and initialised if necessary) by the build process. This
+  variable is ignored if the component is outside the IDF_PATH
+  directory.
 
-  See `Component Requirements` for more details.
 
 Optional Component-Specific Variables
--------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following variables can be set inside ``component.mk`` to control the build of that component:
 
 - ``COMPONENT_PRIV_INCLUDEDIRS``: Directory paths, must be relative to
   the component directory, which will be added to the include search
   path for this component's source files only.
-- ``COMPONENT_PRIV_REQUIRES`` is a (space-separated) list of components that are required to either compile or link this component's source files. These components' header paths do not propagate to other components which require it, they are only used to compile this component's sources. See `Component Requirements` for more details.
-- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the component directory, which will be searched for source files (``*.cpp``,
-  ``*.c``, ``*.S``). Set this to specify a list of directories which contain source files.
-- ``COMPONENT_SRCS``: Paths to individual source files to compile. Setting this causes ``COMPONENT_SRCDIRS`` to be ignored. Setting this variable instead gives you finer grained control over which files are compiled.
-  If you don't set ``COMPONENT_SRCDIRS`` or ``COMPONENT_SRCS``, your component won't compile a library but it may still add include paths for use when compiling other components or the source files listed in ``MAIN_SRCS``.
-- ``COMPONENT_SRCEXCLUDE``: Paths to source files to exclude from component. Can be set in conjunction with ``COMPONENT_SRCDIRS`` if there is a directory with a large number of source files to include in the component but one or more source files which should not be. Paths can be specified relative to the component directory or absolute.
+- ``COMPONENT_EXTRA_INCLUDES``: Any extra include paths used when
+  compiling the component's source files. These will be prefixed with
+  '-I' and passed as-is to the compiler.  Similar to the
+  ``COMPONENT_PRIV_INCLUDEDIRS`` variable, except these paths are not
+  expanded relative to the component directory.
+- ``COMPONENT_SRCDIRS``: Directory paths, must be relative to the
+  component directory, which will be searched for source files (``*.cpp``,
+  ``*.c``, ``*.S``). Defaults to '.', ie the component directory
+  itself. Override this to specify a different list of directories
+  which contain source files.
+- ``COMPONENT_OBJS``: Object files to compile. Default value is a .o
+  file for each source file that is found in ``COMPONENT_SRCDIRS``.
+  Overriding this list allows you to exclude source files in
+  ``COMPONENT_SRCDIRS`` that would otherwise be compiled. See
+  `Specifying source files`
+- ``COMPONENT_EXTRA_CLEAN``: Paths, relative to the component build
+  directory, of any files that are generated using custom make rules
+  in the component.mk file and which need to be removed as part of
+  ``make clean``. See `Source Code Generation`_ for an example.
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: These
+  targets allow you to fully override the default build behaviour for
+  the component. See `Fully Overriding The Component Makefile`_ for
+  more details.
+- ``COMPONENT_CONFIG_ONLY``: If set, this flag indicates that the component
+  produces no built output at all (ie ``COMPONENT_LIBRARY`` is not built),
+  and most other component variables are ignored. This flag is used for IDF
+  internal components which contain only ``KConfig.projbuild`` and/or
+  ``Makefile.projbuild`` files to configure the project, but no source files.
+- ``CFLAGS``: Flags passed to the C compiler. A default set of
+  ``CFLAGS`` is defined based on project settings. Component-specific
+  additions can be made via ``CFLAGS +=``. It is also possible
+  (although not recommended) to override this variable completely for
+  a component.
+- ``CPPFLAGS``: Flags passed to the C preprocessor (used for .c, .cpp
+  and .S files). A default set of ``CPPFLAGS`` is defined based on
+  project settings. Component-specific additions can be made via
+  ``CPPFLAGS +=``. It is also possible (although not recommended) to
+  override this variable completely for a component.
+- ``CXXFLAGS``: Flags passed to the C++ compiler. A default set of
+  ``CXXFLAGS`` is defined based on project
+  settings. Component-specific additions can be made via ``CXXFLAGS
+  +=``. It is also possible (although not recommended) to override
+  this variable completely for a component.
 
-Controlling Component Compilation
----------------------------------
+To apply compilation flags to a single source file, you can add a variable override as a target, ie::
 
-.. highlight:: cmake
-
-To pass compiler options when compiling source files belonging to a particular component, use the ``component_compile_options`` function::
-
-  component_compile_options(-Wno-unused-variable)
-
-This is a wrapper around the CMake `target_compile_options`_ command.
-
-To apply the compilation flags to a single source file, use the CMake `set_source_files_properties`_ command::
-
-    set_source_files_properties(mysrc.c
-        PROPERTIES COMPILE_FLAGS
-        -Wno-unused-variable
-    )
+  apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
 
 This can be useful if there is upstream code that emits warnings.
 
-When using these commands, place them after the ``register_component()`` line in the component CMakeLists file.
-
 Component Configuration
-=======================
+-----------------------
 
-Each component can also have a ``Kconfig`` file, alongside ``CMakeLists.txt``. This contains
-configuration settings to add to the configuration menu for this component.
+Each component can also have a Kconfig file, alongside ``component.mk``. This contains contains
+configuration settings to add to the "make menuconfig" for this component.
 
 These settings are found under the "Component Settings" menu when menuconfig is run.
 
-To create a component Kconfig file, it is easiest to start with one of the Kconfig files distributed with esp-idf.
+To create a component KConfig file, it is easiest to start with one of the KConfig files distributed with esp-idf.
 
 For an example, see `Adding conditional configuration`_.
 
 Preprocessor Definitions
-========================
-
-The ESP-IDF build system adds the following C preprocessor definitions on the command line:
-
-- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
-- ``IDF_VER`` — Defined to a git version string.  E.g. ``v2.0`` for a tagged release or ``v1.0-275-g0efaa4f`` for an arbitrary commit.
-
-Component Requirements
-======================
-
-When compiling each component, the ESP-IDF build system recursively evaluates its components.
-
-Each component's source file is compiled with these include path directories:
-
-- The current component's ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_PRIV_INCLUDEDIRS``.
-- The ``COMPONENT_ADD_INCLUDEDIRS`` set by all components in the current component's ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` variables (ie all the current component's public and private dependencies).
-- All of the ``COMPONENT_REQUIRES`` of those components, evaluated recursively (ie all public dependencies of this component's dependencies, recursively expanded).
-
-When writing a component
 ------------------------
 
-- ``COMPONENT_REQUIRES`` should be set to all components whose header files are #included from the *public* header files of this component.
-- ``COMPONENT_PRIV_REQUIRES`` should be set to all components whose header files are #included from *any source files* of this component, unless already listed in ``COMPONENT_REQUIRES``. Or any component which is required to be linked in order for this component to function correctly.
-- ``COMPONENT_REQUIRES`` and/or ``COMPONENT_PRIV_REQUIRES`` should be set before calling ``register_component()``.
-- The values of ``COMPONENT_REQUIRES`` and ``COMPONENT_PRIV_REQUIRES`` should not depend on any configuration choices (``CONFIG_xxx`` macros). This is because requirements are expanded before configuration is loaded. Other component variables (like include paths or source files) can depend on configuration choices.
-- Not setting either or both ``REQUIRES`` variables is fine. If the component has no requirements except for the "common" components needed for RTOS, libc, etc (``COMPONENT_REQUIRES_COMMON``) then both variables can be empty or unset.
+ESP-IDF build systems adds the following C preprocessor definitions on the command line:
 
-When creating a project
------------------------
-
-- By default, every component is included in the build.
-- If you set the ``COMPONENTS`` variable to a minimal list of components used directly by your project, then the build will include:
-  - Components mentioned explicitly in ``COMPONENTS``.
-  - Those components' requirements (evaluated recursively).
-  - The "common" components that every component depends on.
-- Setting ``COMPONENTS`` to the minimal list of components you need can significantly reduce your project's compile time.
-- When compiling the project's source files (``MAIN_SRCS``), the public header directories (``COMPONENT_ADD_INCLUDEDIRS`` list) of all components included in the build are available.
-
-.. _component-requirements-implementation:
-
-Requirements in the build system implementation
------------------------------------------------
-
-- Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
-- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
-- Configuration is then evaluated for the components included in the build.
-- Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
+- ``ESP_PLATFORM`` — Can be used to detect that build happens within ESP-IDF.
+- ``IDF_VER`` — ESP-IDF version, see `Preset Component Variables`_ for more details.
 
 Build Process Internals
-=======================
+-----------------------
 
-For full details about CMake_ and CMake commands, see the `CMake v3.5 documentation`.
+Top Level: Project Makefile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-project.cmake contents
-----------------------
+- "make" is always run from the project directory and the project makefile, typically named Makefile.
+- The project makefile sets ``PROJECT_NAME`` and optionally customises other `optional project variables`
+- The project makefile includes ``$(IDF_PATH)/make/project.mk`` which contains the project-level Make logic.
+- ``project.mk`` fills in default project-level make variables and includes make variables from the project configuration. If the generated makefile containing project configuration is out of date, then it is regenerated (via targets in ``project_config.mk``) and then the make process restarts from the top.
+- ``project.mk`` builds a list of components to build, based on the default component directories or a custom list of components set in `optional project variables`.
+- Each component can set some `optional project-wide component variables`_. These are included via generated makefiles named ``component_project_vars.mk`` - there is one per component. These generated makefiles are included into ``project.mk``. If any are missing or out of date, they are regenerated (via a recursive make call to the component makefile) and then the make process restarts from the top.
+- `Makefile.projbuild` files from components are included into the make process, to add extra targets or configuration. 
+- By default, the project makefile also generates top-level build & clean targets for each component and sets up `app` and `clean` targets to invoke all of these sub-targets.
+- In order to compile each component, a recursive make is performed for the component makefile.
 
-When included from a project CMakeLists file, the ``project.cmake`` file defines some utility modules and global variables and then sets ``IDF_PATH`` if it was not set in the system environmenmt.
+To better understand the project make process, have a read through the ``project.mk`` file itself.
 
-It also defines an overriden custom version of the built-in CMake_ ``project`` function. This function is overriden to add all of the ESP-IDF specific project functionality.
+Second Level: Component Makefiles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-project function
-----------------
+- Each call to a component makefile goes via the ``$(IDF_PATH)/make/component_wrapper.mk`` wrapper makefile.
+- This component wrapper includes all component ``Makefile.componentbuild`` files, making any recipes, variables etc in these files available to every component.
+- The ``component_wrapper.mk`` is called with the current directory set to the component build directory, and the ``COMPONENT_MAKEFILE`` variable is set to the absolute path to ``component.mk``.
+- ``component_wrapper.mk`` sets default values for all `component variables`, then includes the `component.mk` file which can override or modify these.
+- If ``COMPONENT_OWNBUILDTARGET`` and ``COMPONENT_OWNCLEANTARGET`` are not defined, default build and clean targets are created for the component's source files and the prerequisite ``COMPONENT_LIBRARY`` static library file.
+- The ``component_project_vars.mk`` file has its own target in ``component_wrapper.mk``, which is evaluated from ``project.mk`` if this file needs to be rebuilt due to changes in the component makefile or the project configuration.
 
-The custom ``project()`` function performs the following steps:
+To better understand the component make process, have a read through the ``component_wrapper.mk`` file and some of the ``component.mk`` files included with esp-idf.
 
-- Evaluates component dependencies and builds the ``BUILD_COMPONENTS`` list of components to include in the build (see :ref:`above<component-requirements-implementation>`).
-- Finds all components in the project (searching ``COMPONENT_DIRS`` and filtering by ``COMPONENTS`` if this is set).
-- Loads the project configuration from the ``sdkconfig`` file and produces a ``sdkconfig.cmake`` file and ``sdkconfig.h`` header, to define config values in CMake and C/C++, respectively. If the project configuration changes, cmake will automatically be re-run to reconfigure the project.
-- Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
-- Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
-- Load the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
-- Include ``project_include.cmake`` files from any components which have them.
-- Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the CMake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
-- Add the final app executable to the build.
-- Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
+Running Make Non-Interactively
+------------------------------
 
-Browse the :idf_file:`/tools/cmake/project.cmake` file and supporting functions in :idf_file:`/tools/cmake/idf_functions.cmake` for more details.
+When running ``make`` in a situation where you don't want interactive prompts (for example: inside an IDE or an automated build system) append ``BATCH_BUILD=1`` to the make arguments (or set it as an environment variable).
 
-Debugging CMake
----------------
+Setting ``BATCH_BUILD`` implies the following:
 
-Some tips for debugging the esp-idf CMake-based build system:
+- Verbose output (same as ``V=1``, see below). If you don't want verbose output, also set ``V=0``.
+- If the project configuration is missing new configuration items (from new components or esp-idf updates) then the project use the default values, instead of prompting the user for each item.
+- If the build system needs to invoke ``menuconfig``, an error is printed and the build fails.
 
-- When CMake runs, it prints quite a lot of diagnostic information including lists of components and component paths.
-- Running ``cmake`` with the ``--trace`` or ``--trace-expand`` options will give a lot of information about control flow. See the `cmake command line documentation`_.
+Debugging The Make Process
+--------------------------
+
+Some tips for debugging the esp-idf build system:
+
+- Appending ``V=1`` to the make arguments (or setting it as an environment variable) will cause make to echo all commands executed, and also each directory as it is entered for a sub-make.
+- Running ``make -w`` will cause make to echo each directory as it is entered for a sub-make - same as ``V=1`` but without also echoing all commands.
+- Running ``make --trace`` (possibly in addition to one of the above arguments) will print out every target as it is built, and the dependency which caused it to be built.
+- Running ``make -p`` prints a (very verbose) summary of every generated target in each makefile.
+
+For more debugging tips and general make information, see the `GNU Make Manual`.
 
 .. _warn-undefined-variables:
 
 Warning On Undefined Variables
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-By default, ``idf.py`` passes the ``--warn-uninitialized`` flag to CMake_ so it will print a warning if an undefined variable is referenced in the build. This can be very useful to find buggy CMake files.
+By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names.
 
-If you don't want this behaviour, it can be disabled by passing ``--no-warnings`` to ``idf.py``.
+If you don't want this behaviour, it can be disabled in menuconfig's top level menu under `SDK tool configuration`.
+
+Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles.
 
 Overriding Parts of the Project
 -------------------------------
 
-project_include.cmake
-^^^^^^^^^^^^^^^^^^^^^
+Makefile.projbuild
+^^^^^^^^^^^^^^^^^^
 
-For components that have build requirements which must be evaluated before any component CMakeLists
-files are evaluated, you can create a file called ``project_include.cmake`` in the
-component directory. This CMake file is included when ``project.cmake`` is evaluating the entire project.
+For components that have build requirements that must be evaluated in the top-level
+project make pass, you can create a file called ``Makefile.projbuild`` in the
+component directory. This makefile is included when ``project.mk`` is evaluated.
 
-``project_include.cmake`` files are used inside ESP-IDF, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
+For example, if your component needs to add to CFLAGS for the entire
+project (not just for its own source files) then you can set
+``CFLAGS +=`` in Makefile.projbuild.
 
-Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
+``Makefile.projbuild`` files are used heavily inside esp-idf, for defining project-wide build features such as ``esptool.py`` command line arguments and the ``bootloader`` "special app".
 
-Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
+Note that ``Makefile.projbuild`` isn't necessary for the most common component uses - such as adding include directories to the project, or LDFLAGS to the final linking step. These values can be customised via the ``component.mk`` file itself. See `Optional Project-Wide Component Variables`_ for details.
+
+Take care when setting variables or targets in this file. As the values are included into the top-level project makefile pass, they can influence or break functionality across all components!
 
 KConfig.projbuild
 ^^^^^^^^^^^^^^^^^
 
-This is an equivalent to ``project_include.cmake`` for `component configuration` KConfig files. If you want to include
-configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``CMakeLists.txt`` file.
+This is an equivalent to ``Makefile.projbuild`` for `component configuration` KConfig files. If you want to include
+configuration options at the top-level of menuconfig, rather than inside the "Component Configuration" sub-menu, then these can be defined in the KConfig.projbuild file alongside the ``component.mk`` file.
 
 Take care when adding configuration values in this file, as they will be included across the entire project configuration. Where possible, it's generally better to create a KConfig file for `component configuration`.
 
 
+Makefile.componentbuild
+^^^^^^^^^^^^^^^^^^^^^^^
+
+For components that e.g. include tools to generate source files from other files, it is necessary to be able to add recipes, macros or variable definitions
+into the component build process of every components. This is done by having a ``Makefile.componentbuild`` in a component directory. This file gets included
+in ``component_wrapper.mk``, before the ``component.mk`` of the component is included. As with the Makefile.projbuild, take care with these files: as they're
+included in each component build, a ``Makefile.componentbuild`` error may only show up when compiling an entirely different component.
+
 Configuration-Only Components
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Special components which contain no source files, only ``Kconfig.projbuild`` and ``KConfig``, can have a one-line ``CMakeLists.txt`` file which calls the function ``register_config_only_component()``. This function will include the component in the project build, but no library will be built *and* no header files will be added to any include paths.
+Some special components which contain no source files, only ``Kconfig.projbuild`` and ``Makefile.projbuild``, may set the flag ``COMPONENT_CONFIG_ONLY`` in the component.mk file. If this flag is set, most other component variables are ignored and no build step is run for the component.
 
-If a CMakeLists.txt file doesn't call ``register_component()`` or ``register_config_only_component()``, it will be excluded from the project entirely. This may sometimes be desirable, depending on the project configuration.
-
-Example Component CMakeLists
-============================
+Example Component Makefiles
+---------------------------
 
 Because the build environment tries to set reasonable defaults that will work most
-of the time, component ``CMakeLists.txt`` can be very small or even empty (see `Minimal Component CMakeLists`_). However, overriding `component variables`_ is usually required for some functionality.
+of the time, component.mk can be very small or even empty (see `Minimal Component Makefile`_). However, overriding `component variables` is usually required for some functionality.
 
-Here are some more advanced examples of component CMakeLists files.
+Here are some more advanced examples of ``component.mk`` makefiles:
+
+
+Adding source directories
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, sub-directories are ignored. If your project has sources in sub-directories
+instead of in the root of the component then you can tell that to the build
+system by setting ``COMPONENT_SRCDIRS``::
+
+    COMPONENT_SRCDIRS := src1 src2
+
+This will compile all source files in the src1/ and src2/ sub-directories
+instead.
+
+Specifying source files
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The standard component.mk logic adds all .S and .c files in the source
+directories as sources to be compiled unconditionally. It is possible
+to circumvent that logic and hard-code the objects to be compiled by
+manually setting the ``COMPONENT_OBJS`` variable to the name of the
+objects that need to be generated::
+
+    COMPONENT_OBJS := file1.o file2.o thing/filea.o thing/fileb.o anotherthing/main.o
+    COMPONENT_SRCDIRS := . thing anotherthing
+
+Note that ``COMPONENT_SRCDIRS`` must be set as well.
 
 Adding conditional configuration
---------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The configuration system can be used to conditionally compile some files
-depending on the options selected in the project configuration.
-
-.. highlight:: none
+depending on the options selected in ``make menuconfig``. For this, ESP-IDF
+has the compile_only_if and compile_only_if_not macros:
 
 ``Kconfig``::
 
@@ -512,15 +455,17 @@ depending on the options selected in the project configuration.
         help
             This enables the BAR feature of the FOO component.
 
-``CMakeLists.txt``::
+``component.mk``::
 
-    set(COMPONENT_SRCS "foo.c" "more_foo.c")
+    $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
 
-    if(CONFIG_FOO_ENABLE_BAR)
-        list(APPEND COMPONENT_SRCS "bar.c")
-    endif(CONFIG_FOO_ENABLE_BAR)
 
-This example makes use of the CMake `if function <cmake if_>`_ and `list APPEND <cmake list_>`_ function.
+As can be seen in the example, the ``compile_only_if`` macro takes a condition and a 
+list of object files as parameters. If the condition is true (in this case: if the
+BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will
+always be compiled. The opposite goes as well: if the condition is not true, bar.o 
+will never be compiled. ``compile_only_if_not`` does the opposite: compile if the 
+condition is false, not compile if the condition is true.
 
 This can also be used to select or stub out an implementation, as such:
 
@@ -543,24 +488,28 @@ This can also be used to select or stub out an implementation, as such:
         help
             Select this to output temperature plots
 
-.. highlight:: cmake
 
-``CMakeLists.txt``::
+``component.mk``::
 
-    if(CONFIG_ENABLE_LCD_OUTPUT)
-       set(COMPONENT_SRCS lcd-real.c lcd-spi.c)
-    else()
-       set(COMPONENT_SRCS lcd-dummy.c)
-    endif()
+    # If LCD is enabled, compile interface to it, otherwise compile dummy interface
+    $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
+    $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
 
-    # We need font if either console or plot is enabled
-    if(CONFIG_ENABLE_LCD_CONSOLE OR CONFIG_NEABLE_LCD_PLOT)
-      list(APPEND COMPONENT_SRCS "font.c")
-    endif()
+    #We need font if either console or plot is enabled
+    $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
 
+Note the use of the Make 'or' function to include the font file. Other substitution functions,
+like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also 
+be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains 
+only whitespace to be false while a variable with any non-whitespace in it is true.
+
+(Note: Older versions of this document advised conditionally adding object file names to
+``COMPONENT_OBJS``. While this still is possible, this will only work when all object 
+files for a component are named explicitely, and will not clean up deselected object files
+in a ``make clean`` pass.)
 
 Source Code Generation
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^
 
 Some components will have a situation where a source file isn't
 supplied with the component itself but has to be generated from
@@ -569,369 +518,104 @@ converted binary data of a BMP file, converted using a hypothetical
 tool called bmp2h. The header file is then included in as C source
 file called graphics_lib.c::
 
-    add_custom_command(OUTPUT logo.h
-         COMMAND bmp2h -i ${COMPONENT_PATH}/logo.bmp -o log.h
-         DEPENDS ${COMPONENT_PATH}/logo.bmp
-         VERBATIM)
+    COMPONENT_EXTRA_CLEAN := logo.h
 
-    add_custom_target(logo DEPENDS logo.h)
-    add_dependencies(${COMPONENT_NAME} logo)
+    graphics_lib.o: logo.h
 
-    set_property(DIRECTORY "${COMPONENT_PATH}" APPEND PROPERTY
-         ADDITIONAL_MAKE_CLEAN_FILES logo.h)
+    logo.h: $(COMPONENT_PATH)/logo.bmp
+        bmp2h -i $^ -o $@
 
-This answer is adapted from the `CMake FAQ entry <cmake faq generated files_>`_, which contains some other examples that will also work with ESP-IDF builds.
 
-In this example, logo.h will be generated in the
+In this example, graphics_lib.o and logo.h will be generated in the
 current directory (the build directory) while logo.bmp comes with the
 component and resides under the component path. Because logo.h is a
-generated file, it should be cleaned when the project is cleaned. For this reason
-it is added to the `ADDITIONAL_MAKE_CLEAN_FILES`_ property.
+generated file, it needs to be cleaned when make clean is called which
+why it is added to the COMPONENT_EXTRA_CLEAN variable.
 
-(Note: If generating files as part of the project CMakeLists, not a component CMakeLists, use ``${PROJECT_PATH}`` instead of ``${COMPONENT_PATH}`` and ``${PROJECT_NAME}.elf`` instead of ``${COMPONENT_NAME}``.)
+Cosmetic Improvements
+^^^^^^^^^^^^^^^^^^^^^
 
-If a a source file from another component included ``logo.h``, then ``add_dependencies`` would need to be called to add a dependency between
-the two components, to ensure that the component source files were always compiled in the correct order.
+Because logo.h is a generated file, it needs to be cleaned when make
+clean is called which why it is added to the COMPONENT_EXTRA_CLEAN
+variable.
+
+Adding logo.h to the ``graphics_lib.o`` dependencies causes it to be
+generated before ``graphics_lib.c`` is compiled.
+
+If a a source file in another component included ``logo.h``, then this
+component's name would have to be added to the other component's
+``COMPONENT_DEPENDS`` list to ensure that the components were built
+in-order.
 
 Embedding Binary Data
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 Sometimes you have a file with some binary or text data that you'd like to make available to your component - but you don't want to reformat the file as C source.
 
-You can set a variable ``COMPONENT_EMBED_FILES`` in your component's CMakeLists, giving the names of the files to embed in this way::
+You can set a variable COMPONENT_EMBED_FILES in component.mk, giving the names of the files to embed in this way::
 
-  set(COMPONENT_EMBED_FILES server_root_cert.der)
+  COMPONENT_EMBED_FILES := server_root_cert.der
 
-Or if the file is a string, you can use the variable ``COMPONENT_EMBED_TXTFILES``. This will embed the contents of the text file as a null-terminated string::
+Or if the file is a string, you can use the variable COMPONENT_EMBED_TXTFILES. This will embed the contents of the text file as a null-terminated string::
 
-  set(COMPONENT_EMBED_TXTFILES server_root_cert.pem)
-
-.. highlight:: c
+  COMPONENT_EMBED_TXTFILES := server_root_cert.pem
 
 The file's contents will be added to the .rodata section in flash, and are available via symbol names as follows::
 
   extern const uint8_t server_root_cert_pem_start[] asm("_binary_server_root_cert_pem_start");
   extern const uint8_t server_root_cert_pem_end[]   asm("_binary_server_root_cert_pem_end");
 
-The names are generated from the full name of the file, as given in ``COMPONENT_EMBED_FILES``. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
-
-.. highlight:: cmake
-
-To embed a file into a project, rather than a component, you can call the function ``target_add_binary_data`` like this::
-
-  target_add_binary_data(myproject.elf "main/data.bin" TEXT)
-
-Place this line after the ``project()`` line in your project CMakeLists.txt file. Replace ``myproject.elf`` with your project name. The final argument can be ``TEXT`` to embed a null-terminated string, or ``BINARY`` to embed the content as-is.
+The names are generated from the full name of the file, as given in COMPONENT_EMBED_FILES. Characters /, ., etc. are replaced with underscores. The _binary prefix in the symbol name is added by objcopy and is the same for both text and binary files.
 
 For an example of using this technique, see :example:`protocols/https_request` - the certificate file contents are loaded from the text .pem file at compile time.
 
-.. _component-build-full-override:
 
-Fully Overriding The Component Build Process
---------------------------------------------
-
-.. highlight:: cmake
+Fully Overriding The Component Makefile
+---------------------------------------
 
 Obviously, there are cases where all these recipes are insufficient for a
 certain component, for example when the component is basically a wrapper
 around another third-party component not originally intended to be
 compiled under this build system. In that case, it's possible to forego
-the esp-idf build system entirely by using a CMake feature called ExternalProject_. Example component CMakeLists::
+the esp-idf build system entirely by setting COMPONENT_OWNBUILDTARGET and
+possibly  COMPONENT_OWNCLEANTARGET and defining your own targets named ``build`` and ``clean`` in ``component.mk``
+target. The build target can do anything as long as it creates
+$(COMPONENT_LIBRARY) for the project make process to link into the app binary.
 
-  # External build process for quirc, runs in source dir and
-  # produces libquirc.a
-  externalproject_add(quirc_build
-      PREFIX ${COMPONENT_PATH}
-      SOURCE_DIR ${COMPONENT_PATH}/quirc
-      CONFIGURE_COMMAND ""
-      BUILD_IN_SOURCE 1
-      BUILD_COMMAND make CC=${CMAKE_C_COMPILER} libquirc.a
-      INSTALL_COMMAND ""
-      )
+(Actually, even this is not strictly necessary - if the COMPONENT_ADD_LDFLAGS variable
+is overridden then the component can instruct the linker to link other binaries instead.)
 
-   # Add libquirc.a to the build process
-   #
-   add_library(quirc STATIC IMPORTED GLOBAL)
-   add_dependencies(quirc quirc_build)
 
-   set_target_properties(quirc PROPERTIES IMPORTED_LOCATION
-        ${COMPONENT_PATH}/quirc/libquirc.a)
-   set_target_properties(quirc PROPERTIES INTERFACE_INCLUDE_DIRECTORIES
-        ${COMPONENT_PATH}/quirc/lib)
+.. _esp-idf-template: https://github.com/espressif/esp-idf-template
+.. _GNU Make Manual: https://www.gnu.org/software/make/manual/make.html
 
-   set_directory_properties( PROPERTIES ADDITIONAL_MAKE_CLEAN_FILES
-        "${COMPONENT_PATH}/quirc/libquirc.a")
-
-(The above CMakeLists.txt can be used to create a component named ``quirc`` that builds the quirc_ project using its own Makefile.)
-
-- ``externalproject_add`` defines an external build system.
-  - ``SOURCE_DIR``, ``CONFIGURE_COMMAND``, ``BUILD_COMMAND`` and ``INSTALL_COMMAND`` should always be set. ``CONFIGURE_COMMAND`` can be set to an empty string if the build system has no "configure" step. ``INSTALL_COMMAND`` will generally be empty for ESP-IDF builds.
-  - Setting ``BUILD_IN_SOURCE`` means the build directory is the same as the source directory. Otherwise you can set ``BUILD_DIR``.
-  - Consult the ExternalProject_ documentation for more details about ``externalproject_add()``
-
-- The second set of commands adds a library target, which points to the "imported" library file built by the external system. Some properties need to be set in order to add include directories and tell CMake where this file is.
-- Finally, the generated library is added to `ADDITIONAL_MAKE_CLEAN_FILES`_. This means ``make clean`` will delete this library. (Note that the other object files from the build won't be deleted.)
-
-.. _ADDITIONAL_MAKE_CLEAN_FILES_note:
-
-ExternalProject dependencies, clean builds
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-CMake has some unusual behaviour around external project builds:
-
-- `ADDITIONAL_MAKE_CLEAN_FILES`_ only works when "make" is used as the build system. If Ninja_ or an IDE build system is used, it won't delete these files when cleaning.
-- However, the ExternalProject_ configure & build commands will *always* be re-run after a clean is run.
-- Therefore, there are two alternative recommended ways to configure the external build command:
-
-    1. Have the external ``BUILD_COMMAND`` run a full clean compile of all sources. The build command will be run if any of the dependencies passed to ``externalproject_add`` with ``DEPENDS`` have changed, or if this is a clean build (ie any of ``idf.py clean``, ``ninja clean``, or ``make clean`` was run.)
-    2. Have the external ``BUILD_COMMAND`` be an incremental build command. Pass the parameter ``BUILD_ALWAYS 1`` to ``externalproject_add``. This means the external project will be built each time a build is run, regardless of dependencies. This is only recommended if the external project has correct incremental build behaviour, and doesn't take too long to run.
-
-The best of these approaches for building an external project will depend on the project itself, its build system, and whether you anticipate needing to frequently recompile the project.
 
 .. _custom-sdkconfig-defaults:
 
 Custom sdkconfig defaults
-=========================
+-------------------------
 
-For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when creating a new config from scratch, or when any new config value hasn't yet been set in the ``sdkconfig`` file.
+For example projects or other projects where you don't want to specify a full sdkconfig configuration, but you do want to override some key values from the esp-idf defaults, it is possible to create a file ``sdkconfig.defaults`` in the project directory. This file will be used when running ``make defconfig``, or creating a new config from scratch.
 
 To override the name of this file, set the ``SDKCONFIG_DEFAULTS`` environment variable.
 
 
-Flash arguments
-===============
+Save flash arguments
+--------------------
 
-There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py.
+There're some scenarios that we want to flash the target board without IDF. For this case we want to save the built binaries, esptool.py and esptool write_flash arguments. It's simple to write a script to save binaries and esptool.py. We can use command ``make print_flash_cmd``, it will print the flash arguments::
 
-After running a project build, the build directory contains binary output files (``.bin`` files) for the project and also the following flashing data files:
+    --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 
-- ``flash_project_args`` contains arguments to flash the entire project (app, bootloader, partition table, PHY data if this is configured).
-- ``flash_app_args`` contains arguments to flash only the app.
-- ``flash_bootloader_args`` contains arguments to flash only the bootloader.
+Then use flash arguments as the arguemnts for esptool write_flash arguments::
 
-.. highlight:: bash
-
-You can pass any of these flasher argument files to ``esptool.py`` as follows::
-
-  python esptool.py --chip esp32 write_flash @build/flash_project_args
-
-Alternatively, it is possible to manually copy the parameters from the argument file and pass them on the command line.
-
-The build directory also contains a generated file ``flasher_args.json`` which contains project flash information, in JSON format. This file is used by ``idf.py`` and can also be used by other tools which need information about the project build.
+    python esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0x1000 bootloader/bootloader.bin 0x10000 example_app.bin 0x8000 partition_table_unit_test_app.bin
 
 Building the Bootloader
 =======================
 
-The bootloader is built by default as part of ``idf.py build``, or can be built standalone via ``idf.py bootloader``.
+The bootloader is built by default as part of "make all", or can be built standalone via "make bootloader-clean". There is also "make bootloader-list-components" to see the components included in the bootloader build.
 
-The bootloader is a special "subproject" inside :idf:`/components/bootloader/subproject`. It has its own project CMakeLists.txt file and builds separate .ELF and .BIN files to the main project. However it shares its configuration and build directory with the main project.
-
-The subproject is inserted as an external project from the top-level project, by the file :idf_file:`/components/bootloader/project_include.cmake`. The main build process runs CMake for the subproject, which includes discovering components (a subset of the main components) and generating a bootloader-specific config (derived from the main ``sdkconfig``).
-
-Writing Pure CMake Components
-=============================
-
-The ESP-IDF build system "wraps" CMake with the concept of "components", and helper functions to automatically integrate these components into a project build.
-
-However, underneath the concept of "components" is a full CMake build system. It is also possible to make a component which is pure CMake.
-
-.. highlight:: cmake
-
-Here is an example minimal "pure CMake" component CMakeLists file for a component named ``json``::
-
-  add_library(json STATIC
-  cJSON/cJSON.c
-  cJSON/cJSON_Utils.c)
-
-  target_include_directories(json PUBLIC cJSON)
-
-- This is actually an equivalent declaration to the IDF ``json`` component :idf_file:`/components/json/CMakeLists.txt`.
-- This file is quite simple as there are not a lot of source files. For components with a large number of files, the globbing behaviour of ESP-IDF's component logic can make the component CMakeLists style simpler.)
-- Any time a component adds a library target with the component name, the ESP-IDF build system will automatically add this to the build, expose public include directories, etc. If a component wants to add a library target with a different name, dependencies will need to be added manually via CMake commands.
-
-
-File Globbing & Incremental Builds
-==================================
-
-.. highlight:: cmake
-
-The preferred way to include source files in an ESP-IDF component is to set ``COMPONENT_SRC_DIRS``::
-
-  set(COMPONENT_SRCDIRS library platform)
-
-The build system will automatically find (via "file globbing") all source files in this directory. Alternatively, files can be specified individually::
-
-  set(COMPONENT_SRCS library/a.c library/b.c platform/platform.c)
-
-Usually, CMake_ recommends always to name all files individually (ie ``COMPONENT_SRCS``). This is because CMake is automatically re-run whenever a CMakeLists file changes. If a new source file is added and file globbing is used, then CMake won't know to automatically re-run and this file won't be added to the build.
-
-The tradeoff is acceptable when you're adding the file yourself, because you can trigger a clean build or run ``idf.py reconfigure`` to manually re-run CMake_. However, the problem gets harder when you share your project with others who may check out a new version using a source control tool like Git...
-
-For components which are part of ESP-IDF, we use a third party Git CMake integration module (:idf_file:`/tools/cmake/third_party/GetGitRevisionDescription.cmake`) which automatically re-runs CMake any time the repository commit changes. This means if you check out a new ESP-IDF version, CMake will automatically rerun.
-
-For project CMakeLists files, ``MAIN_SRCS`` is a list of source files. Therefore if a new file is added, CMakeLists will change and this triggers a re-run of CMake. (This is "the CMake way" to do things.)
-
-For project components (not part of ESP-IDF), there are a few options:
-
-- If keeping your project file in Git, ESP-IDF will automatically track the Git revision and re-run CMake if the revision changes.
-- If some components are kept in a third git repo (not the project repo or ESP-IDF repo), you can add a call to the ``git_describe`` function in a component CMakeLists file in order to trigger re-runs of CMake.
-- If not using Git, you remember to manually run ``idf.py reconfigure`` whenever a source file may change.
-- Use ``COMPONENT_SRCS`` to list all source files in project components.
-
-The best option will depend on your particular project and its users.
-
-Build System Metadata
-=====================
-
-For integration into IDEs and other build systems, when CMake runs the build process generates a number of metadata files in the ``build/`` directory. To regenerate these files, run ``cmake`` or ``idf.py reconfigure`` (or any other ``idf.py`` build command).
-
-- ``compile_commands.json`` is a standard format JSON file which describes every source file which is compiled in the project. A CMake feature generates this file, and many IDEs know how to parse it.
-- ``project_description.json`` contains some general information about the ESP-IDF project, configured paths, etc.
-- ``flasher_args.json`` contains esptool.py arguments to flash the project's binary files. There are also ``flash_*_args`` files which can be used directly with esptool.py. See `Flash arguments`_.
-- ``CMakeCache.txt`` is the CMake cache file which contains other information about the CMake process, toolchain, etc.
-- ``config/sdkconfig.json`` is a JSON-formatted version of the project configuration values.
-- ``config/kconfig_menus.json`` is a JSON-formatted version of the menus shown in menuconfig, for use in external IDE UIs.
-
-JSON Configuration Server
--------------------------
-
-.. highlight :: json
-
-A tool called ``confserver.py`` is provided to allow IDEs to easily integrate with the configuration system logic. ``confserver.py`` is designed to run in the background and interact with a calling process by reading and writing JSON over process stdin & stdout.
-
-You can run ``confserver.py`` from a project via ``idf.py confserver`` or ``ninja confserver``, or a similar target triggered from a different build generator.
-
-The config server outputs human-readable errors and warnings on stderr and JSON on stdout. On startup, it will output the full values of each configuration item in the system as a JSON dictionary, and the available ranges for values which are range constrained. The same information is contained in ``sdkconfig.json``::
-
-  {"version": 1, "values": { "ITEM": "value", "ITEM_2": 1024, "ITEM_3": false }, "ranges" : { "ITEM_2" : [ 0, 32768 ] } }
-
-Only visible configuration items are sent. Invisible/disabled items can be parsed from the static ``kconfig_menus.json`` file which also contains the menu structure and other metadata (descriptions, types, ranges, etc.)
-
-The Configuration Server will then wait for input from the client. The client passes a request to change one or more values, as a JSON object followed by a newline::
-
-   {"version": "1", "set": {"SOME_NAME": false, "OTHER_NAME": true } }
-
-The Configuration Server will parse this request, update the project ``sdkconfig`` file, and return a full list of changes::
-
-   {"version": 1, "values": {"SOME_NAME": false, "OTHER_NAME": true , "DEPENDS_ON_SOME_NAME": null}}
-
-Items which are now invisible/disabled will return value ``null``. Any item which is newly visible will return its newly visible current value.
-
-If the range of a config item changes, due to conditional range depending on another value, then this is also sent::
-
-   {"version": 1, "values": {"OTHER_NAME": true }, "ranges" : { "HAS_RANGE" : [ 3, 4 ] } }
-
-If invalid data is passed, an "error" field is present on the object::
-
-    {"version": 1, "values": {}, "error": ["The following config symbol(s) were not visible so were not updated: NOT_VISIBLE_ITEM"]}
-
-By default, no config changes are written to the sdkconfig file. Changes are held in memory until a "save" command is sent::
-
-    {"version": 1, "save": null }
-
-To reload the config values from a saved file, discarding any changes in memory, a "load" command can be sent::
-
-    {"version": 1, "load": null }
-
-The value for both "load" and "save" can be a new pathname, or "null" to load/save the previous pathname.
-
-The response to a "load" command is always the full set of config values and ranges, the same as when the server is initially started.
-
-Any combination of "load", "set", and "save" can be sent in a single command and commands are executed in that order. Therefore it's possible to load config from a file, set some config item values and then save to a file in a single command.
-
-.. note:: The configuration server does not automatically load any changes which are applied externally to the ``sdkconfig`` file. Send a "load" command or restart the server if the file is externally edited.
-
-.. note:: The configuration server does not re-run CMake to regenerate other build files or metadata files after ``sdkconfig`` is updated. This will happen automatically the next time ``CMake`` or ``idf.py`` is run.
-
-.. _gnu-make-to-cmake:
-
-Migrating from ESP-IDF GNU Make System
-======================================
-
-Some aspects of the CMake-based ESP-IDF build system are very similar to the older GNU Make-based system. For example, to adapt a ``component.mk`` file to ``CMakeLists.txt`` variables like ``COMPONENT_ADD_INCLUDEDIRS`` and ``COMPONENT_SRCDIRS`` can stay the same and the syntax only needs changing to CMake syntax.
-
-Automatic Conversion Tool
--------------------------
-
-.. highlight:: bash
-
-An automatic project conversion tool is available in :idf_file:`/tools/cmake/convert_to_cmake.py`. Run this command line tool with the path to a project like this::
-
-    $IDF_PATH/tools/cmake/convert_to_cmake.py /path/to/project_dir
-
-The project directory must contain a Makefile, and GNU Make (``make``) must be installed and available on the PATH.
-
-The tool will convert the project Makefile and any component ``component.mk`` files to their equivalent ``CMakeLists.txt`` files.
-
-It does so by running ``make`` to expand the ESP-IDF build system variables which are set by the build, and then producing equivalent CMakelists files to set the same variables.
-
-The conversion tool is not capable of dealing with complex Makefile logic or unusual targets. These will need to be converted by hand.
-
-'main' is no longer a component
--------------------------------
-
-In the GNU Make build system ``main`` is a component with a ``component.mk`` file like other components.
-
-Due to CMake requirements for building executables, ``main`` source files are now linked directly into the final binary. The source files in ``main`` must be listed in the ``MAIN_SRCS`` variable (see :ref:`project mandatory variables <project-mandatory-parts>` for more details). At least one source file has to be listed here (although it doesn't need to contain anything in particular).
-
-In general, it's better not to have too many source files in ``MAIN_SRCS``. If you find that you are adding many source files here, see if you reorganize and group some into project components (see the :ref:`example project structure <example-project-structure>`, above).
-
-No Longer Available in CMake
-----------------------------
-
-Some features are significantly different or removed in the CMake-based system. The following variables no longer exist in the CMake-based build system:
-
-- ``COMPONENT_BUILD_DIR``: Use ``CMAKE_CURRENT_BINARY_DIR`` instead.
-- ``COMPONENT_LIBRARY``: Defaulted to ``$(COMPONENT_NAME).a``, but the library name could be overriden by the component. The name of the component library can no longer be overriden by the component.
-- ``CC``, ``LD``, ``AR``, ``OBJCOPY``: Full paths to each tool from the gcc xtensa cross-toolchain. Use ``CMAKE_C_COMPILER``, ``CMAKE_C_LINK_EXECUTABLE``, ``CMAKE_OBJCOPY``, etc instead. `Full list here <cmake language variables_>`_.
-- ``HOSTCC``, ``HOSTLD``, ``HOSTAR``: Full names of each tool from the host native toolchain. These are no longer provided, external projects should detect any required host toolchain manually.
-- ``COMPONENT_ADD_LDFLAGS``: Used to override linker flags. Use the CMake `target_link_libraries`_ command instead.
-- ``COMPONENT_ADD_LINKER_DEPS``: List of files that linking should depend on. `target_link_libraries`_ will usually infer these dependencies automatically. For linker scripts, use the provided custom CMake function ``target_linker_scripts``.
-- ``COMPONENT_SUBMODULES``: No longer used, the build system will automatically enumerate all submodules in the ESP-IDF repo.
-- ``COMPONENT_EXTRA_INCLUDES``: Used to be an alternative to ``COMPONENT_PRIV_INCLUDEDIRS`` for absolute paths. Use ``COMPONENT_PRIV_INCLUDEDIRS`` for all cases now (can be relative or absolute).
-- ``COMPONENT_OBJS``: Previously, component sources could be specified as a list of object files. Now they can be specified as an list of source files via ``COMPONENT_SRCS``.
-- ``COMPONENT_OBJEXCLUDE``: Has been replaced with ``COMPONENT_SRCEXCLUDE``. Specify source files (as absolute paths or relative to component directory), instead.
-- ``COMPONENT_EXTRA_CLEAN``: Set property ``ADDITIONAL_MAKE_CLEAN_FILES`` instead but note :ref:`CMake has some restrictions around this functionality <ADDITIONAL_MAKE_CLEAN_FILES_note>`.
-- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``: Use CMake `ExternalProject`_ instead. See :ref:`component-build-full-override` for full details.
-- ``COMPONENT_CONFIG_ONLY``: Call ``register_config_only_component()`` instead. See `Configuration-Only Components`_.
-- ``CFLAGS``, ``CPPFLAGS``, ``CXXFLAGS``: Use equivalent CMake commands instead. See `Controlling Component Compilation`_.
-
-
-No Default Values
------------------
-
-The following variables no longer have default values:
-
-- ``COMPONENT_SRCDIRS``
-- ``COMPONENT_ADD_INCLUDEDIRS``
-
-No Longer Necessary
--------------------
-
-It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCDIRS`` is ignored if ``COMPONENT_SRCS`` is set).
-
-
-.. _esp-idf-template: https://github.com/espressif/esp-idf-template
-.. _cmake: https://cmake.org
-.. _ninja: https://ninja-build.org
-.. _esptool.py: https://github.com/espressif/esptool/#readme
-.. _CMake v3.5 documentation_: https://cmake.org/cmake/help/v3.5/index.html
-.. _cmake command line documentation: https://cmake.org/cmake/help/v3.5/manual/cmake.1.html#options
-.. _cmake add_library: https://cmake.org/cmake/help/v3.5/command/project.html
-.. _cmake if: https://cmake.org/cmake/help/v3.5/command/if.html
-.. _cmake list: https://cmake.org/cmake/help/v3.5/command/list.html
-.. _cmake project: https://cmake.org/cmake/help/v3.5/command/project.html
-.. _cmake set: https://cmake.org/cmake/help/v3.5/command/set.html
-.. _cmake string: https://cmake.org/cmake/help/v3.5/command/string.html
-.. _cmake faq generated files: https://cmake.org/Wiki/CMake_FAQ#How_can_I_generate_a_source_file_during_the_build.3F
-.. _ADDITIONAL_MAKE_CLEAN_FILES: https://cmake.org/cmake/help/v3.5/prop_dir/ADDITIONAL_MAKE_CLEAN_FILES.html
-.. _ExternalProject: https://cmake.org/cmake/help/v3.5/module/ExternalProject.html
-.. _cmake language variables: https://cmake.org/cmake/help/v3.5/manual/cmake-variables.7.html#variables-for-languages
-.. _set_source_files_properties: https://cmake.org/cmake/help/v3.5/command/set_source_files_properties.html
-.. _target_compile_options: https://cmake.org/cmake/help/v3.5/command/target_compile_options.html
-.. _target_link_libraries: https://cmake.org/cmake/help/v3.5/command/target_link_libraries.html#command:target_link_libraries
-.. _cmake_toolchain_file: https://cmake.org/cmake/help/v3.5/variable/CMAKE_TOOLCHAIN_FILE.html
-.. _quirc: https://github.com/dlbeer/quirc
-.. _pyenv: https://github.com/pyenv/pyenv#README
-.. _virtualenv: https://virtualenv.pypa.io/en/stable/
+The component in IDF components/bootloader is special, as the second stage bootloader is a separate .ELF and .BIN file to the main project. However it shares its configuration and build directory with the main project.
 
+This is accomplished by adding a subproject under components/bootloader/subproject. This subproject has its own Makefile, but it expects to be called from the project's own Makefile via some glue in the components/bootloader/Makefile.projectbuild file. See these files for more details.
diff --git a/docs/en/api-guides/gnu-make-build-system.rst b/docs/en/api-guides/gnu-make-build-system.rst
deleted file mode 100644
index d1a8a41f9..000000000
--- a/docs/en/api-guides/gnu-make-build-system.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-GNU Make Build System
-*********************
-
-This document contains a "cheat sheet" for users of the older ESP-IDF GNU Make build system and the newer CMake build system.
-
-Currently, this version of ESP-IDF contains support for both build systems, and either build system can be used. However, the rest of the documentation for this version has been updated for the CMake build system.
-
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view dedicated documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
-Dependencies
-============
-
-For Linux & Mac OS, the dependencies for the GNU Make and CMake-based build systems are very similar. The only additional tool required for GNU Make is ``make`` 3.81 or newer. This is pre-installed on Mac OS and can be installed on Linux via the distribution package manager.
-
-For Windows, the requirements are different as the GNU Make based build system requires MSYS2 for a Unix compatibility layer. Consult the Getting Started docs for IDF v3.0 for steps to set up MSYS2.
-
-Cheat Sheet
-===========
-
-Equivalents between GNU make-based build system commands and the CMake-based build system:
-
-====================  ==================  =================
-Summary               CMake-based         GNU Make based
-====================  ==================  =================
-Configure project     idf.py menuconfig   make menuconfig
-Build project         idf.py build        make
-Flash project         idf.py flash        make flash
-Monitor project       idf.py monitor      make monitor
-Clean project         idf.py fullclean    make clean
-====================  ==================  =================
-
-To override the default build directory:
-
-- CMake based: ``idf.py -b (directory) build``
-- GNU Make based: ``make BUILD_DIR_BASE=(directory)``.
-
-To set the serial port for flashing/monitoring:
-
-- CMake based: ``idf.py -p (port) flash``
-- GNU Make based: ``make flash ESPPORT=/dev/ttyUSB0``, or set in ``menuconfig``.
-
-(Note: ``idf.py`` will also use the ``ESPPORT`` environment variable for a default serial port, if no ``-p`` argument is provided.)
-
-To set the baud rate for flashing:
-
-- CMake based: ``idf.py -b 921600 flash``
-- GNU Make based: ``make flash ESPBAUD=921600``, or set in ``menuconfig``.
-
-(Note: ``idf.py`` will also use the ``ESPBAUD`` environment variable for a default baud rate, if no ``-b`` argument is provided.)
-
-Porting GNU Make Based Components to CMake
-==========================================
-
-See :ref:`gnu-make-to-cmake`.
diff --git a/docs/en/api-guides/index.rst b/docs/en/api-guides/index.rst
index 3e8b2ece5..21ec7d69a 100644
--- a/docs/en/api-guides/index.rst
+++ b/docs/en/api-guides/index.rst
@@ -6,6 +6,7 @@ API Guides
 
    General Notes <general-notes>
    Build System <build-system>
+   Build System (CMake) <build-system-cmake>
    Deep Sleep Wake Stubs <deep-sleep-stub>
    ESP32 Core Dump <core_dump>
    Flash Encryption <../security/flash-encryption>
diff --git a/docs/en/cmake-pending-features.rst b/docs/en/cmake-pending-features.rst
new file mode 100644
index 000000000..1ea28a913
--- /dev/null
+++ b/docs/en/cmake-pending-features.rst
@@ -0,0 +1,10 @@
+.. important::
+   The following features are not yet supported with the CMake-based build system:
+
+   - Eclipse IDE Documentation
+   - Secure Boot
+   - Flash Encryption
+   - ULP toolchain.
+
+   Support for these features will be available before CMake becomes the default build system.
+
diff --git a/docs/en/cmake-warning.rst b/docs/en/cmake-warning.rst
new file mode 100644
index 000000000..3f97614f4
--- /dev/null
+++ b/docs/en/cmake-warning.rst
@@ -0,0 +1,4 @@
+.. note::
+   This is documentation for the CMake-based build system which is currently in preview release. If you encounter any gaps or bugs, please report them in the `Issues <https://github.com/espressif/esp-idf/issues>`_ section of the ESP-IDF repository.
+
+   The CMake-based build system will become the default build system in ESP-IDF V4.0. The existing GNU Make based build system will be deprecated in ESP-IDF V5.0.
diff --git a/docs/en/get-started-cmake/add-idf_path-to-profile.rst b/docs/en/get-started-cmake/add-idf_path-to-profile.rst
new file mode 100644
index 000000000..a3b3a471e
--- /dev/null
+++ b/docs/en/get-started-cmake/add-idf_path-to-profile.rst
@@ -0,0 +1,73 @@
+Add IDF_PATH & idf.py PATH to User Profile (CMake)
+==================================================
+
+.. include:: ../cmake-warning.rst
+
+To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
+
+- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
+- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
+
+To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
+
+.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
+
+.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
+
+.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
+
+.. _add-paths-to-profile-windows-cmake:
+
+Windows
+-------
+
+To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
+
+On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
+
+You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
+
+- Click ``New...`` to add a new system variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\user-name\esp\esp-idf``.
+- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
+
+If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
+
+
+.. _add-idf_path-to-profile-linux-macos-cmake:
+
+Linux and MacOS
+---------------
+
+Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
+
+    export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:$IDF_PATH/tools"
+
+.. note::
+
+   ``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
+
+Log off and log in back to make this change effective.
+
+.. note::
+
+    Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
+
+Run the following command to check if ``IDF_PATH`` is set::
+
+    printenv IDF_PATH
+
+The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
+
+To verify idf.py is now on the ``PATH``, you can run the following::
+
+  which idf.py
+
+A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
+
+If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
+
+    export IDF_PATH=~/esp/esp-idf
+    export PATH="$PATH:$IDF_PATH/tools"
+
+If you got here from section :ref:`get-started-setup-path-cmake`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project-cmake`.
diff --git a/docs/en/get-started-cmake/eclipse-setup.rst b/docs/en/get-started-cmake/eclipse-setup.rst
new file mode 100644
index 000000000..ccc546f34
--- /dev/null
+++ b/docs/en/get-started-cmake/eclipse-setup.rst
@@ -0,0 +1,10 @@
+****************************************
+Build and Flash with Eclipse IDE (CMake)
+****************************************
+
+.. include:: ../cmake-warning.rst
+
+Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
+
+.. _eclipse.org: https://www.eclipse.org/
+
diff --git a/docs/en/get-started-cmake/establish-serial-connection.rst b/docs/en/get-started-cmake/establish-serial-connection.rst
new file mode 100644
index 000000000..ca0e4dd2c
--- /dev/null
+++ b/docs/en/get-started-cmake/establish-serial-connection.rst
@@ -0,0 +1,131 @@
+Establish Serial Connection with ESP32 (CMake)
+==============================================
+
+
+This section provides guidance how to establish serial connection between ESP32 and PC.
+
+
+Connect ESP32 to PC
+--------------------
+
+Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
+
+Below are the links to drivers for ESP32 boards produced by Espressif:
+
+* ESP32-PICO-KIT and ESP32-DevKitC - `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
+
+* ESP32-WROVER-KIT and ESP32 Demo Board - `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
+
+Above drivers are primarily for reference. They should already be bundled with the operating system and installed automatically once one of listed boards is connected to the PC.
+
+
+Check port on Windows
+---------------------
+
+Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again.
+
+Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
+
+.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
+    :align: center
+    :alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager
+    :figclass: align-center
+
+    USB to UART bridge of ESP32-DevKitC in Windows Device Manager
+
+.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
+    :align: center
+    :alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
+    :figclass: align-center
+
+    Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
+
+
+Check port on Linux and MacOS
+-----------------------------
+
+To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
+
+Linux ::
+
+    ls /dev/tty*
+
+MacOS ::
+
+    ls /dev/cu.*
+
+
+.. note: MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
+
+.. _linux-dialout-group-cmake:
+
+Adding user to ``dialout`` on Linux
+-----------------------------------
+
+The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command::
+
+    sudo usermod -a -G dialout $USER
+
+Make sure you re-login to enable read and write permissions for the serial port. 
+
+
+Verify serial connection
+------------------------
+
+Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client <http://www.putty.org/>`_ that is available for both Windows and Linux. You can use other serial program and set communication parameters like below.
+
+Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as  115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
+
+.. figure:: ../../_static/putty-settings-windows.png
+    :align: center
+    :alt: Setting Serial Communication in PuTTY on Windows
+    :figclass: align-center
+
+    Setting Serial Communication in PuTTY on Windows
+
+.. figure:: ../../_static/putty-settings-linux.png
+    :align: center
+    :alt: Setting Serial Communication in PuTTY on Linux
+    :figclass: align-center
+
+    Setting Serial Communication in PuTTY on Linux
+
+
+Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below.
+
+.. highlight:: none
+
+::
+
+    ets Jun  8 2016 00:22:57
+
+    rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+    ets Jun  8 2016 00:22:57
+
+    rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+    configsip: 0, SPIWP:0x00
+    clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
+    mode:DIO, clock div:2
+    load:0x3fff0008,len:8
+    load:0x3fff0010,len:3464
+    load:0x40078000,len:7828
+    load:0x40080000,len:252
+    entry 0x40080034
+    I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
+    I (45) boot: compile time 18:48:10
+
+    ...
+
+If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
+
+.. note::
+
+   For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
+
+.. note::
+
+   Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
+
+If you got here from section :ref:`get-started-connect-cmake` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure-cmake`.
+
+.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
diff --git a/docs/en/get-started-cmake/get-started-devkitc-v2.rst b/docs/en/get-started-cmake/get-started-devkitc-v2.rst
new file mode 100644
index 000000000..fd566387e
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-devkitc-v2.rst
@@ -0,0 +1,80 @@
+ESP32-DevKitC V2 Getting Started Guide (CMake)
+==============================================
+
+This user guide shows how to get started with ESP32-DevKitC development board.
+
+
+What You Need
+-------------
+
+* 1 × :ref:`ESP32-DevKitC V2 board <get-started-esp32-devkitc-v2-board-front-cmake>`
+* 1 × USB A / micro USB B cable 
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+
+Overview
+--------
+
+ESP32-DevKitC is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard.
+
+
+Functional Description
+----------------------
+
+The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC board.
+
+ESP-WROOM-32
+    Standard `ESP-WROOM-32 <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ module soldered to the ESP32-DevKitC board.
+EN
+    Reset button: pressing this button resets the system.
+Boot
+    Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
+USB
+    USB interface. It functions as the power supply for the board and the communication interface between PC and ESP-WROOM-32.
+I/O
+    Most of the pins on the ESP-WROOM-32 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
+
+.. _get-started-esp32-devkitc-v2-board-front-cmake:
+
+.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png
+    :align: center
+    :alt: ESP32-DevKitC V2 board layout
+    :figclass: align-center
+
+    ESP32-DevKitC V2 board layout
+
+
+Power Supply Options
+--------------------
+
+There following options are available to provide power supply to this board:
+
+1. Micro USB port, this is default power supply connection
+2. 5V / GND header pins
+3. 3V3 / GND header pins
+
+.. warning::
+
+    Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
+
+
+Start Application Development
+------------------------------
+
+Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Related Documents
+-----------------
+
+* `ESP32-DevKitC schematic <https://dl.espressif.com/dl/schematics/ESP32-Core-Board-V2_sch.pdf>`_ (PDF)
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
+* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
diff --git a/docs/en/get-started-cmake/get-started-devkitc.rst b/docs/en/get-started-cmake/get-started-devkitc.rst
new file mode 100644
index 000000000..20b2d86f6
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-devkitc.rst
@@ -0,0 +1,114 @@
+ESP32-DevKitC V4 Getting Started Guide (CMake)
+==============================================
+
+This user guide shows how to get started with ESP32-DevKitC V4 development board. For description of other versions of the ESP32-DevKitC check :doc:`../hw-reference/index`.
+
+
+What You Need
+-------------
+
+* 1 × :ref:`ESP32-DevKitC V4 board <get-started-esp32-devkitc-board-front-cmake>`
+* 1 × USB A / micro USB B cable 
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+
+Overview
+--------
+
+ESP32-DevKitC V4 is a small-sized ESP32-based development board produced by `Espressif <https://espressif.com>`_. Most of the I/O pins are broken out to the pin headers on both sides for easy interfacing. Developers can connect these pins to peripherals as needed. Standard headers also make development easy and convenient when using a breadboard. 
+
+The board comes in two versions, either with :ref:`esp-modules-and-boards-esp-wroom-32` or :ref:`esp-modules-and-boards-esp32-wrover` module soldered.
+
+
+Functional Description
+----------------------
+
+The following list and figure below describe key components, interfaces and controls of ESP32-DevKitC V4 board.
+
+ESP-WROOM-32
+    :ref:`esp-modules-and-boards-esp-wroom-32` module soldered to the ESP32-DevKitC V4 board.
+ESP32-WROVER
+    Optionally :ref:`esp-modules-and-boards-esp32-wrover` module may be soldered instead of the ESP-WROOM-32.
+USB-UART Bridge
+    A single chip USB-UART bridge provides up to 3 Mbps transfers rates.
+Boot
+    Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
+Micro USB Port
+    USB interface. It functions as the power supply for the board and the communication interface between PC and the ESP module.
+5V Power On LED
+    This LED lights when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
+EN
+    Reset button: pressing this button resets the system.
+I/O
+    Most of the pins on the ESP module are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
+
+    .. note::
+
+        Some of broken out pins are used internally be the ESP32 module to communicate with SPI memory. They are grouped on one side of the board besides the USB connector and labeled D0, D1, D2, D3, CMD and CLK. In general these pins should be left unconnected or access to the SPI flash memory / SPI RAM may be disturbed. 
+
+    .. note::
+
+        GPIO16 and 17 are used internally by the ESP32-WROVER module. They are broken out and avialable for use only for boards that have the ESP-WROOM-32 module installed.
+
+
+.. _get-started-esp32-devkitc-board-front-cmake:
+
+.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg
+    :align: center
+    :alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
+    :figclass: align-center
+
+    ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
+
+
+Power Supply Options
+--------------------
+
+There following options are available to provide power supply to this board:
+
+1. Micro USB port, this is default power supply connection
+2. 5V / GND header pins
+3. 3V3 / GND header pins
+
+.. warning::
+
+    Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
+
+
+Start Application Development
+------------------------------
+
+Before powering up the ESP32-DevKitC, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Board Dimensions
+----------------
+
+.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg
+    :align: center
+    :alt: ESP32 DevKitC board dimensions - back
+    :figclass: align-center
+
+    ESP32 DevKitC board dimensions - back
+
+
+Related Documents
+-----------------
+
+* `ESP32-DevKitC V4 schematic <https://dl.espressif.com/dl/schematics/esp32_devkitc_v4-sch.pdf>`_ (PDF)
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
+* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
+
+.. toctree::
+    :hidden:
+
+    get-started-devkitc-v2
diff --git a/docs/en/get-started-cmake/get-started-pico-kit-v3.rst b/docs/en/get-started-cmake/get-started-pico-kit-v3.rst
new file mode 100644
index 000000000..3abd213d4
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-pico-kit-v3.rst
@@ -0,0 +1,67 @@
+ESP32-PICO-KIT V3 Getting Started Guide (CMake)
+===============================================
+
+This user guide shows how to get started with the ESP32-PICO-KIT V3 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
+
+
+What You Need
+-------------
+
+* 1 × ESP32-PICO-KIT V3 mini development board
+* 1 × USB A / Micro USB B cable
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+
+Overview
+--------
+
+ESP32-PICO-KIT V3 is a mini development board based on the ESP32-PICO-D4 SIP module produced by `Espressif <https://espressif.com>`_. All the IO signals and system power on ESP32-PICO-D4 are led out through two standard 20 pin x 0.1" pitch headers on both sides for easy interfacing. The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the development board to a PC's USB port for downloads and debugging.
+
+
+Functional Description
+----------------------
+
+The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V3 board.
+
+ESP32-PICO-D4
+    Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V3 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
+USB-UART Bridge
+    A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
+I/O
+    All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
+Micro USB Port
+    USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V3.
+EN Button
+    Reset button; pressing this button resets the system.
+BOOT Button
+    Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
+
+.. figure:: ../../_static/esp32-pico-kit-v3-layout.jpg
+    :align: center
+    :alt: ESP32-PICO-KIT V3 board layout
+    :figclass: align-center
+
+    ESP32-PICO-KIT V3 board layout
+
+
+Start Application Development
+------------------------------
+
+Before powering up the ESP32-PICO-KIT V3, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Related Documents
+-----------------
+
+* `ESP32-PICO-KIT V3 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v3_schematic.pdf>`_ (PDF)
+* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
+* :doc:`../hw-reference/index`
+
diff --git a/docs/en/get-started-cmake/get-started-pico-kit.rst b/docs/en/get-started-cmake/get-started-pico-kit.rst
new file mode 100644
index 000000000..9d73f34cb
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-pico-kit.rst
@@ -0,0 +1,213 @@
+ESP32-PICO-KIT V4 Getting Started Guide (CMake)
+===============================================
+
+
+This user guide shows how to get started with the ESP32-PICO-KIT V4 mini development board. For description of other versions of the ESP32-PICO-KIT check :doc:`../hw-reference/index`.
+
+
+What You Need
+-------------
+
+* 1 × :ref:`ESP32-PICO-KIT V4 mini development board <get-started-pico-kit-v4-board-front-cmake>`
+* 1 × USB A / Micro USB B cable
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+If you like to start using this board right now, go directly to section `Start Application Development`_.
+
+
+Overview
+--------
+
+ESP32-PICO-KIT V4 is a mini development board produced by `Espressif <https://espressif.com>`_. At the core of this board is the ESP32-PICO-D4, a System-in-Package (SIP) module with complete Wi-Fi and Bluetooth functionalities. Comparing to other ESP32 chips, the ESP32-PICO-D4 integrates several peripheral components in one single package, that otherwise would need to be installed separately. This includes a 40 MHz crystal oscillator, 4 MB flash, filter capacitors and RF matching links in. This greatly reduces quantity and costs of additional components, subsequent assembly and testing cost, as well as overall product complexity.
+
+The development board integrates a USB-UART Bridge circuit, allowing the developers to connect the board to a PC's USB port for downloads and debugging. 
+
+For easy interfacing, all the IO signals and system power on ESP32-PICO-D4 are led out through two rows of 20 x 0.1" pitch header pads on both sides of the development board. To make the ESP32-PICO-KIT V4 fit into mini breadboards, the header pads are populated with two rows of 17 pin headers. Remaining 2 x 3 pads grouped on each side of the board besides the antenna are not populated. The remaining 2 x 3 pin headers may be soldered later by the user. 
+
+.. note::
+
+    The 2 x 3 pads not populated with pin headers are internally connected to the flash memory embedded in the ESP32-PICO-D4 SIP module. For more details see module's datasheet in `Related Documents`_.
+
+The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see section `Board Dimensions`_. An overview functional block diagram is shown below.
+
+.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png
+    :align: center
+    :alt: ESP32-PICO-KIT V4 functional block diagram
+    :figclass: align-center
+
+    ESP32-PICO-KIT V4 functional block diagram
+
+
+Functional Description
+----------------------
+
+The following list and figure below describe key components, interfaces and controls of ESP32-PICO-KIT V4 board.
+
+ESP32-PICO-D4
+    Standard ESP32-PICO-D4 module soldered to the ESP32-PICO-KIT V4 board. The complete system of the ESP32 chip has been integrated into the SIP module, requiring only external antenna with LC matching network, decoupling capacitors and pull-up resistors for EN signals to function properly.
+LDO
+    5V-to-3.3V Low dropout voltage regulator (LDO).
+USB-UART Bridge
+    A single chip USB-UART bridge provides up to 1 Mbps transfers rates.
+Micro USB Port
+    USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32-PICO-KIT V4.
+5V Power On LED
+    This light emitting diode lits when the USB or an external 5V power supply is applied to the board. For details see schematic in `Related Documents`_.
+I/O
+    All the pins on ESP32-PICO-D4 are broken out to the pin headers on the board. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc. For details please see section `Pin Descriptions`_.
+BOOT Button
+    Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
+EN Button
+    Reset button; pressing this button resets the system.
+
+.. _get-started-pico-kit-v4-board-front-cmake:
+
+.. figure:: ../../_static/esp32-pico-kit-v4-layout.jpg
+    :align: center
+    :alt: ESP32-PICO-KIT V4 board layout
+    :figclass: align-center
+
+    ESP32-PICO-KIT V4 board layout
+
+
+Power Supply Options
+--------------------
+
+There following options are available to provide power supply to the ESP32-PICO-KIT V4:
+
+1. Micro USB port, this is default power supply connection
+2. 5V / GND header pins
+3. 3V3 / GND header pins
+
+.. warning::
+
+    Above options are mutually exclusive, i.e. the power supply may be provided using only one of the above options. Attempt to power the board using more than one connection at a time may damage the board and/or the power supply source.
+
+
+Start Application Development
+-----------------------------
+
+Before powering up the ESP32-PICO-KIT V4, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Pin Descriptions
+----------------
+
+The two tables below provide the **Name** and **Function** of I/O headers on both sides of the board, see :ref:`get-started-pico-kit-v4-board-front-cmake`. The pin numbering and header names are the same as on a schematic in `Related Documents`_.
+
+
+Header J2
+"""""""""
+
+======  =================  ======  ======================================================
+No.     Name               Type    Function
+======  =================  ======  ======================================================
+1       FLASH_SD1 (FSD1)   I/O     | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2CTS
+2       FLASH_SD3 (FSD3)   I/O     | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RTS
+3       FLASH_CLK (FCLK)   I/O     | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U1CTS 
+4       IO21               I/O     | GPIO21, VSPIHD, EMAC_TX_EN
+5       IO22               I/O     | GPIO22, VSPIWP, U0RTS, EMAC_TXD1
+6       IO19               I/O     | GPIO19, VSPIQ, U0CTS, EMAC_TXD0
+7       IO23               I/O     | GPIO23, VSPID, HS1_STROBE
+8       IO18               I/O     | GPIO18, VSPICLK, HS1_DATA7
+9       IO5                I/O     | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
+10      IO10               I/O     | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD
+11      IO9                I/O     | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD
+12      RXD0               I/O     | GPIO3, U0RXD :ref:`(4) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT2
+13      TXD0               I/O     | GPIO1, U0TXD :ref:`(4) <get-started-pico-kit-v4-pin-notes-cmake>` , CLK_OUT3, EMAC_RXD2
+14      IO35               I       | ADC1_CH7, RTC_GPIO5
+15      IO34               I       | ADC1_CH6, RTC_GPIO4
+16      IO38               I       | GPIO38, ADC1_CH2, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes-cmake>` , RTC_GPIO2
+17      IO37               I       | GPIO37, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH1, RTC_GPIO1
+18      EN                 I       | CHIP_PU
+19      GND                P       | Ground
+20      VDD33 (3V3)        P       | 3.3V power supply
+======  =================  ======  ======================================================
+
+
+Header J3
+"""""""""
+
+======  =================  ======  ======================================================
+No.     Name               Type    Function
+======  =================  ======  ======================================================
+1       FLASH_CS (FCS)     I/O     | GPIO16, HS1_DATA4 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2RXD, EMAC_CLK_OUT
+2       FLASH_SD0 (FSD0)   I/O     | GPIO17, HS1_DATA5 :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U2TXD, EMAC_CLK_OUT_180
+3       FLASH_SD2 (FSD2)   I/O     | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(1) <get-started-pico-kit-v4-pin-notes-cmake>` , U1RTS
+4       SENSOR_VP (FSVP)   I       | GPIO36, ADC1_CH0, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes-cmake>` , RTC_GPIO0
+5       SENSOR_VN (FSVN)   I       | GPIO39, ADC1_CH3, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes-cmake>` , RTC_GPIO3
+6       IO25               I/O     | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
+7       IO26               I/O     | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
+8       IO32               I/O     | 32K_XP :ref:`(3a) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH4, TOUCH9, RTC_GPIO9
+9       IO33               I/O     | 32K_XN :ref:`(3b) <get-started-pico-kit-v4-pin-notes-cmake>` , ADC1_CH5, TOUCH8, RTC_GPIO8
+10      IO27               I/O     | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17
+                                   | EMAC_RX_DV
+11      IO14               I/O     | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,
+                                   | HS2_CLK, SD_CLK, EMAC_TXD2
+12      IO12               I/O     | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(5) <get-started-pico-kit-v4-pin-notes-cmake>` , HSPIQ,
+                                   | HS2_DATA2, SD_DATA2, EMAC_TXD3
+13      IO13               I/O     | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,
+                                   | HS2_DATA3, SD_DATA3, EMAC_RX_ER
+14      IO15               I/O     | ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0
+                                   | HS2_CMD, SD_CMD, EMAC_RXD3
+15      IO2                I/O     | ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,
+                                   | HS2_DATA0, SD_DATA0
+16      IO4                I/O     | ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,
+                                   | HS2_DATA1, SD_DATA1, EMAC_TX_ER
+17      IO0                I/O     | ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1
+                                   | EMAC_TX_CLK
+18      VDD33 (3V3)        P       | 3.3V power supply
+19      GND                P       | Ground
+20      EXT_5V (5V)        P       | 5V power supply
+======  =================  ======  ======================================================
+
+
+.. _get-started-pico-kit-v4-pin-notes-cmake:
+
+**Notes to** `Pin Descriptions`_ 
+
+    1. This pin is connected to the flash pin of ESP32-PICO-D4.
+    2. When used as ADC_PRE_AMP, connect 270 pF capacitors between: (a) SENSOR_VP and IO37, (b) SENSOR_VN and IO38.
+    3. 32.768 kHz crystal oscillator: (a) input, (b) output.
+    4. This pin is connected to the pin of the USB bridge chip on the board.
+    5. The operating voltage of ESP32-PICO-KIT’s embedded SPI flash is 3.3V. Therefore, the strapping pin MTDI should hold bit ”0” during the module power-on reset.
+
+
+Board Dimensions
+----------------
+
+.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-back.jpg
+    :align: center
+    :alt: ESP32-PICO-KIT V4 dimensions - back
+    :figclass: align-center
+
+    ESP32-PICO-KIT V4 dimensions - back
+
+.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg
+    :align: center
+    :alt: ESP32-PICO-KIT V4 dimensions - side
+    :figclass: align-center
+
+    ESP32-PICO-KIT V4 dimensions - side
+
+
+Related Documents
+-----------------
+
+* `ESP32-PICO-KIT V4 schematic <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v4_schematic.pdf>`_ (PDF)
+* `ESP32-PICO-D4 Datasheet <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
+* :doc:`../hw-reference/index`
+
+
+.. toctree::
+    :hidden:
+
+    get-started-pico-kit-v3
diff --git a/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst b/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst
new file mode 100644
index 000000000..c10325fb3
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-wrover-kit-v2.rst
@@ -0,0 +1,192 @@
+ESP-WROVER-KIT V2 Getting Started Guide (CMake)
+===============================================
+
+This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
+
+If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-v2-start-development-cmake`.
+
+
+What You Need
+-------------
+
+* 1 × ESP-WROVER-KIT V2 board
+* 1 x Micro USB 2.0 Cable, Type A to Micro B
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+
+Overview
+^^^^^^^^
+
+The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
+
+.. note::
+
+    ESP-WROVER-KIT V2 integrates the ESP-WROOM-32 module by default.
+
+
+Functionality Overview
+^^^^^^^^^^^^^^^^^^^^^^
+
+Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
+
+.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
+    :align: center
+    :alt: ESP-WROVER-KIT block diagram
+    :figclass: align-center
+
+    ESP-WROVER-KIT block diagram
+
+
+Functional Description
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
+
+32.768 kHz
+    An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
+ESP32 Module
+    ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
+
+    .. note::
+
+        GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
+
+CTS/RTS
+    Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
+UART
+    Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
+SPI
+    SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. If an ESP32-WROVER is being used, please note that the electrical level on the flash and SRAM is 1.8V.
+JTAG
+    JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
+FT2232
+    FT2232 chip is a multi-protocol USB-to-serial bridge. The FT2232 chip features USB-to-UART and USB-to-JTAG functionalities. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32.
+
+    The embedded FT2232 chip is one of the distinguishing features of the ESP-WROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, uses do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V2 schematic`_.
+EN
+    Reset button: pressing this button resets the system.
+Boot
+    Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
+USB
+    USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
+Power Select
+    Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`esp-wrover-kit-v2-setup-options-cmake`, jumper header JP7.
+Power Key
+    Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
+5V Input
+    The 5V power supply interface is used as a backup power supply in case of full-load operation.
+LDO
+    NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V2 schematic`_.
+Camera
+    Camera interface: a standard OV7670 camera module is supported.
+RGB
+    Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
+I/O
+    All the pins on the ESP32 module are led out to the pin headers on the ESPWROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
+
+Micro SD Card
+    Micro SD card slot for data storage: when ESP32 enters the download mode, GPIO2 cannot be held high. However, a pull-up resistor is required on GPIO2 to enable the Micro SD Card. By default, GPIO2 and the pull-up resistor R153 are disconnected. To enable the SD Card, use jumpers on JP1 as shown in section :ref:`esp-wrover-kit-v2-setup-options-cmake`.
+LCD
+    ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-kit-v2-board-back-cmake`.
+
+.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png
+    :align: center
+    :alt: ESP-WROVER-KIT board layout - front
+    :figclass: align-center
+
+    ESP-WROVER-KIT board layout - front
+
+.. _esp-wrover-kit-v2-board-back-cmake:
+
+.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png
+    :align: center
+    :alt: ESP-WROVER-KIT board layout - back
+    :figclass: align-center
+
+    ESP-WROVER-KIT board layout - back
+
+
+.. _esp-wrover-kit-v2-setup-options-cmake:
+
+Setup Options
+^^^^^^^^^^^^^
+
+There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+
++--------+----------------------+-------------------------------------------------+
+| Header | Jumper Setting       | Description of Functionality                    |
++--------+----------------------+-------------------------------------------------+
+|  JP1   | |jp1-sd_io2|         | Enable pull up for the Micro SD Card            |
++--------+----------------------+-------------------------------------------------+
+|  JP1   | |jp1-both|           | Assert GPIO2 low during each download           |
+|        |                      | (by jumping it to GPIO0)                        |
++--------+----------------------+-------------------------------------------------+
+|  JP7   | |jp7-ext_5v|         | Power ESP-WROVER-KIT board from an external     |
+|        |                      | power supply                                    |
++--------+----------------------+-------------------------------------------------+
+|  JP7   | |jp7-usb_5v|         | Power ESP-WROVER-KIT board from an USB port     |
++--------+----------------------+-------------------------------------------------+
+|  JP8   | |jp8|                | Enable JTAG functionality                       |
++--------+----------------------+-------------------------------------------------+
+|  JP11  | |jp11-rx-tx|         | Enable UART communication                       |
++--------+----------------------+-------------------------------------------------+
+|  JP14  | |jp14|               | Enable RTS/CTS flow control for serial          |
+|        |                      | communication                                   |
++--------+----------------------+-------------------------------------------------+
+
+
+.. _esp-wrover-kit-v2-start-development-cmake:
+
+Start Application Development
+-----------------------------
+
+Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+
+Initial Setup
+^^^^^^^^^^^^^
+
+Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+
++----------------------+----------------------+
+| Power up             | Enable UART          |
+| from USB port        | communication        |
++----------------------+----------------------+
+| |jp7-usb_5v|         | |jp11-rx-tx|         |
++----------------------+----------------------+
+
+Do not install any other jumpers.
+
+
+Now to Development
+^^^^^^^^^^^^^^^^^^
+
+To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Related Documents
+-----------------
+
+* `ESP-WROVER-KIT V2 schematic`_ (PDF)
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
+* `ESP-WROOM-32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
+* :doc:`../api-guides/jtag-debugging/index`
+* :doc:`../hw-reference/index`
+
+
+.. |jp1-sd_io2| image:: ../../_static/wrover-jp1-sd_io2.png
+.. |jp1-both| image:: ../../_static/wrover-jp1-both.png
+.. |jp7-ext_5v| image:: ../../_static/wrover-jp7-ext_5v.png
+.. |jp7-usb_5v| image:: ../../_static/wrover-jp7-usb_5v.png
+.. |jp8| image:: ../../_static/wrover-jp8.png
+.. |jp11-rx-tx| image:: ../../_static/wrover-jp11-tx-rx.png
+.. |jp14| image:: ../../_static/wrover-jp14.png
+
+.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf
diff --git a/docs/en/get-started-cmake/get-started-wrover-kit.rst b/docs/en/get-started-cmake/get-started-wrover-kit.rst
new file mode 100644
index 000000000..c99c62d36
--- /dev/null
+++ b/docs/en/get-started-cmake/get-started-wrover-kit.rst
@@ -0,0 +1,413 @@
+ESP-WROVER-KIT V3 Getting Started Guide (CMake)
+===============================================
+
+This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. For description of other versions of the ESP-WROVER-KIT check :doc:`../hw-reference/index`.
+
+If you like to start using this board right now, go directly to section :ref:`get-started-esp-wrover-kit-start-development-cmake`.
+
+
+What You Need
+-------------
+
+* 1 × :ref:`ESP-WROVER-KIT V3 board <get-started-esp-wrover-kit-board-front-cmake>`
+* 1 x Micro USB 2.0 Cable, Type A to Micro B
+* 1 × PC loaded with Windows, Linux or Mac OS
+
+
+Overview
+^^^^^^^^
+
+The ESP-WROVER-KIT is a development board produced by `Espressif <https://espressif.com>`_ built around ESP32. This board is compatible with ESP32 modules, including the ESP-WROOM-32 and ESP32-WROVER. The ESP-WROVER-KIT features support for an LCD and MicroSD card. The I/O pins have been broken out from the ESP32 module for easy extension. The board carries an advanced multi-protocol USB bridge (the FTDI FT2232HL), enabling developers to use JTAG directly to debug the ESP32 through the USB interface. The development board makes secondary development easy and cost-effective.
+
+.. note::
+
+    ESP-WROVER-KIT V3 integrates the ESP32-WROVER module by default. 
+
+
+Functionality Overview
+^^^^^^^^^^^^^^^^^^^^^^
+
+Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
+
+.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
+    :align: center
+    :alt: ESP-WROVER-KIT block diagram
+    :figclass: align-center
+
+    ESP-WROVER-KIT block diagram
+
+
+Functional Description
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following list and figures below describe key components, interfaces and controls of ESP-WROVER-KIT board.
+
+32.768 kHz
+    An external precision 32.768 kHz crystal oscillator provides the chip with a clock of low-power consumption during the Deep-sleep mode.
+0R
+    A zero Ohm resistor intended as a placeholder for a current shunt. May be desoldered or replaced with a current shunt to facilitate measurement of current required by ESP32 module depending on power mode.
+ESP32 Module
+    ESP-WROVER-KIT is compatible with both ESP-WROOM-32 and ESP32-WROVER. The ESP32-WROVER module features all the functions of ESP-WROOM-32 and integrates an external 32-MBit PSRAM for flexible extended storage and data processing capabilities.
+
+    .. note::
+
+        GPIO16 and GPIO17 are used as the CS and clock signal for PSRAM. To ensure reliable performance, the two GPIOs are not broken out.
+
+FT2232
+    The FT2232 chip is a multi-protocol USB-to-serial bridge. Users can control and program the FT2232 chip through the USB interface to establish communication with ESP32. The FT2232 chip also features USB-to-JTAG interface. USB-to-JTAG is available on channel A of FT2232, USB-to-serial on channel B. The embedded FT2232 chip is one of the distinguishing features of the ESPWROVER-KIT. It enhances users’ convenience in terms of application development and debugging. In addition, users do not need to buy a JTAG debugger separately, which reduces the development cost, see `ESP-WROVER-KIT V3 schematic`_.
+UART
+    Serial port: the serial TX/RX signals on FT2232HL and ESP32 are broken out to the two sides of JP11. By default, the two signals are connected with jumpers. To use the ESP32 module serial interface only, the jumpers may be removed and the module can be connected to another external serial device.
+SPI
+    SPI interface: the SPI interface connects to an external flash (PSRAM). To interface another SPI device, an extra CS signal is needed. The electrical level on the flash of this module is 1.8V. If an ESP-WROOM-32 is being used, please note that the electrical level on the flash of this module is 3.3V.
+CTS/RTS
+    Serial port flow control signals: the pins are not connected to the circuitry by default. To enable them, respective pins of JP14 must be shorted with jumpers.
+JTAG
+    JTAG interface: the JTAG signals on FT2232HL and ESP32 are broken out to the two sides of JP8. By default, the two signals are disconnected. To enable JTAG, shorting jumpers are required on the signals.
+EN
+    Reset button: pressing this button resets the system.
+Boot
+    Download button: holding down the **Boot** button and pressing the **EN** button initiates the firmware download mode. Then user can download firmware through the serial port.
+USB
+    USB interface. It functions as the power supply for the board and the communication interface between PC and ESP32 module.
+Power Select
+    Power supply selection interface: the ESP-WROVER-KIT can be powered through the USB interface or the 5V Input interface. The user can select the power supply with a jumper. More details can be found in section :ref:`get-started-esp-wrover-kit-setup-options-cmake`, jumper header JP7.
+Power Key
+    Power on/off button: toggling to the right powers the board on; toggling to the left powers the board off.
+5V Input
+    The 5V power supply interface is used as a backup power supply in case of full-load operation.
+LDO
+    NCP1117(1A). 5V-to-3.3V LDO. (There is an alternative pin-compatible LDO — LM317DCY, with an output current of up to 1.5A). NCP1117 can provide a maximum current of 1A. The LDO solutions are available with both fixed output voltage and variable output voltage. For details please refer to `ESP-WROVER-KIT V3 schematic`_.
+Camera
+    Camera interface: a standard OV7670 camera module is supported.
+RGB
+    Red, green and blue (RGB) light emitting diodes (LEDs), which may be controlled by pulse width modulation (PWM).
+I/O
+    All the pins on the ESP32 module are led out to the pin headers on the ESP-WROVER-KIT. Users can program ESP32 to enable multiple functions such as PWM, ADC, DAC, I2C, I2S, SPI, etc.
+Micro SD Card
+    Micro SD card slot for data storage.
+LCD
+    ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`get-started-esp-wrover-kit-board-back-cmake`.
+
+.. _get-started-esp-wrover-kit-board-front-cmake:
+
+.. figure:: ../../_static/esp32-wrover-kit-layout-front.jpg
+    :align: center
+    :alt: ESP-WROVER-KIT board layout - front
+    :figclass: align-center
+
+    ESP-WROVER-KIT board layout - front
+
+.. _get-started-esp-wrover-kit-board-back-cmake:
+
+.. figure:: ../../_static/esp32-wrover-kit-layout-back.jpg
+    :align: center
+    :alt: ESP-WROVER-KIT board layout - back
+    :figclass: align-center
+
+    ESP-WROVER-KIT board layout - back
+
+
+.. _get-started-esp-wrover-kit-setup-options-cmake:
+
+Setup Options
+^^^^^^^^^^^^^
+
+There are five jumper headers available to set up the board functionality. Typical options to select from are listed in table below.
+
++--------+------------------+--------------------------------------------------+
+| Header | Jumper Setting   | Description of Functionality                     |
++--------+------------------+--------------------------------------------------+
+|  JP7   | |jp7-ext_5v|     | Power ESP-WROVER-KIT board from an external      |
+|        |                  | power supply                                     |
++--------+------------------+--------------------------------------------------+
+|  JP7   | |jp7-usb_5v|     | Power ESP-WROVER-KIT board from an USB port      |
++--------+------------------+--------------------------------------------------+
+|  JP8   | |jp8|            | Enable JTAG functionality                        |
++--------+------------------+--------------------------------------------------+
+|  JP11  | |jp11-rx-tx|     | Enable UART communication                        |
++--------+------------------+--------------------------------------------------+
+|  JP14  | |jp14|           | Enable RTS/CTS flow control for serial           |
+|        |                  | communication                                    |
++--------+------------------+--------------------------------------------------+
+
+
+Allocation of ESP32 Pins
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Several pins / terminals of ESP32 module are allocated to the on board hardware. Some of them, like GPIO0 or GPIO2, have multiple functions. If certain hardware is not installed, e.g. nothing is plugged in to the Camera / JP4 header, then selected GPIOs may be used for other purposes.
+
+
+Main I/O Connector / JP1
+""""""""""""""""""""""""
+
+The JP1 connector is shown in two columns in the middle under "I/O" headers. The two columns "Shared With" outside, describe where else on the board certain GPIO is used. 
+
++----------------------+------+------+----------------------+
+|          Shared With | I/O  | I/O  | Shared With          |
++======================+======+======+======================+
+|                      | 3.3V | GND  |                      |
++----------------------+------+------+----------------------+
+|              NC/XTAL | IO32 | IO33 | NC/XTAL              |
++----------------------+------+------+----------------------+
+|        JTAG, MicroSD | IO12 | IO13 | JTAG, MicroSD        |
++----------------------+------+------+----------------------+
+|        JTAG, MicroSD | IO14 | IO27 | Camera               |
++----------------------+------+------+----------------------+
+|               Camera | IO26 | IO25 | Camera, LCD          |
++----------------------+------+------+----------------------+
+|               Camera | IO35 | IO34 | Camera               |
++----------------------+------+------+----------------------+
+|               Camera | IO39 | IO36 | Camera               |
++----------------------+------+------+----------------------+
+|                 JTAG | EN   | IO23 | Camera, LCD          |
++----------------------+------+------+----------------------+
+|          Camera, LCD | IO22 | IO21 | Camera, LCD, MicroSD |
++----------------------+------+------+----------------------+
+|          Camera, LCD | IO19 | IO18 | Camera, LCD          |
++----------------------+------+------+----------------------+
+|          Camera, LCD | IO5  | IO17 | PSRAM                |
++----------------------+------+------+----------------------+
+|                PSRAM | IO16 | IO4  | LED, Camera, MicroSD |
++----------------------+------+------+----------------------+
+|            LED, Boot | IO0  | IO2  | LED, Camera, MicroSD |
++----------------------+------+------+----------------------+
+|        JTAG, MicroSD | IO15 | 5V   |                      |
++----------------------+------+------+----------------------+
+
+Legend:
+
+* NC/XTAL - :ref:`32.768 kHz Oscillator <get-started-esp-wrover-kit-xtal-cmake>`
+* JTAG - :ref:`JTAG / JP8 <get-started-esp-wrover-jtag-header-cmake>`
+* Boot - Boot button / SW2
+* Camera - :ref:`Camera / JP4 <get-started-esp-wrover-camera-header-cmake>`
+* LED - :ref:`RGB LED <get-started-esp-wrover-rgb-led-connections-cmake>`
+* MicroSD - :ref:`MicroSD Card / J4 <get-started-esp-wrover-microsd-card-slot-cmake>`
+* LCD - :ref:`LCD / U5 <get-started-esp-wrover-lcd-connector-cmake>`
+* PSRAM - ESP32-WROVER's PSRAM, if ESP32-WROVER is installed
+
+
+.. _get-started-esp-wrover-kit-xtal-cmake:
+
+32.768 kHz Oscillator
+"""""""""""""""""""""
+
++---+-----------+
+|   | ESP32 Pin |
++===+===========+
+| 1 | GPIO32    |
++---+-----------+
+| 2 | GPIO33    |
++---+-----------+
+
+.. note::
+
+    As GPIO32 and GPIO33 are connected to the oscillator, to maintain signal integrity, they are not connected to JP1 I/O expansion connector. This allocation may be changed from oscillator to JP1 by desoldering 0R resistors from positions R11 / R23 and installing them in positions R12 / R24.
+
+
+.. _get-started-esp-wrover-spi-flash-header-cmake:
+
+SPI Flash / JP13
+""""""""""""""""
+
++---+--------------+
+|   | ESP32 Pin    |
++===+==============+
+| 1 | CLK / GPIO6  |
++---+--------------+
+| 2 | SD0 / GPIO7  |
++---+--------------+
+| 3 | SD1 / GPIO8  |
++---+--------------+
+| 4 | SD2 / GPIO9  |
++---+--------------+
+| 5 | SD3 / GPIO10 |
++---+--------------+
+| 6 | CMD / GPIO11 |
++---+--------------+
+
+.. important::
+
+    The module's flash bus is connected to the pin header JP13 through 0-Ohm resistors R140 ~ R145. If the flash frequency needs to operate at 80 MHz, to improve integrity of the bus signals, it is recommended to desolder resistors R140 ~ R145. At this point, the module's flash bus is disconnected with the pin header JP13.
+
+
+.. _get-started-esp-wrover-jtag-header-cmake:
+
+JTAG / JP8
+""""""""""
+
++---+---------------+-------------+
+|   | ESP32 Pin     | JTAG Signal |
++===+===============+=============+
+| 1 | EN            | TRST_N      |
++---+---------------+-------------+
+| 2 | MTDO / GPIO15 | TDO         |
++---+---------------+-------------+
+| 3 | MTDI / GPIO12 | TDI         |
++---+---------------+-------------+
+| 4 | MTCK / GPIO13 | TCK         |
++---+---------------+-------------+
+| 5 | MTMS / GPIO14 | TMS         |
++---+---------------+-------------+
+
+
+.. _get-started-esp-wrover-camera-header-cmake:
+
+Camera / JP4
+""""""""""""
+
++----+--------------+----------------------+
+|    | ESP32 Pin    | Camera Signal        |
++====+==============+======================+
+|  1 | GPIO27       | SCCB Clock           |
++----+--------------+----------------------+
+|  2 | GPIO26       | SCCB Data            |
++----+--------------+----------------------+
+|  3 | GPIO21       | System Clock         |
++----+--------------+----------------------+
+|  4 | GPIO25       | Vertical Sync        |
++----+--------------+----------------------+
+|  5 | GPIO23       | Horizontal Reference |
++----+--------------+----------------------+
+|  6 | GPIO22       | Pixel Clock          |
++----+--------------+----------------------+
+|  7 | GPIO4        | Pixel Data Bit 0     |
++----+--------------+----------------------+
+|  8 | GPIO5        | Pixel Data Bit 1     |
++----+--------------+----------------------+
+|  9 | GPIO18       | Pixel Data Bit 2     |
++----+--------------+----------------------+
+| 10 | GPIO19       | Pixel Data Bit 3     |
++----+--------------+----------------------+
+| 11 | GPIO36       | Pixel Data Bit 4     |
++----+--------------+----------------------+
+| 11 | GPIO39       | Pixel Data Bit 5     |
++----+--------------+----------------------+
+| 11 | GPIO34       | Pixel Data Bit 6     |
++----+--------------+----------------------+
+| 11 | GPIO35       | Pixel Data Bit 7     |
++----+--------------+----------------------+
+| 11 | GPIO2        | Camera Reset         |
++----+--------------+----------------------+
+
+
+.. _get-started-esp-wrover-rgb-led-connections-cmake:
+
+RGB LED
+"""""""
+
++---+-----------+---------+
+|   | ESP32 Pin | RGB LED |
++===+===========+=========+
+| 1 | GPIO0     | Red     |
++---+-----------+---------+
+| 2 | GPIO2     | Blue    |
++---+-----------+---------+
+| 3 | GPIO4     | Green   |
++---+-----------+---------+
+
+
+.. _get-started-esp-wrover-microsd-card-slot-cmake:
+
+MicroSD Card / J4
+"""""""""""""""""
+
++---+---------------+----------------+
+|   | ESP32 Pin     | MicroSD Signal |
++===+===============+================+
+| 1 | MTDI / GPIO12 | DATA2          |
++---+---------------+----------------+
+| 2 | MTCK / GPIO13 | CD / DATA3     |
++---+---------------+----------------+
+| 3 | MTDO / GPIO15 | CMD            |
++---+---------------+----------------+
+| 4 | MTMS / GPIO14 | CLK            |
++---+---------------+----------------+
+| 5 | GPIO2         | DATA0          |
++---+---------------+----------------+
+| 6 | GPIO4         | DATA1          |
++---+---------------+----------------+
+| 7 | GPIO21        | CD             |
++---+---------------+----------------+
+
+
+.. _get-started-esp-wrover-lcd-connector-cmake:
+
+LCD / U5
+""""""""
+
++---+-----------+------------+
+|   | ESP32 Pin | LCD Signal |
++===+===========+============+
+| 1 | GPIO18    | RESET      |
++---+-----------+------------+
+| 2 | GPIO19    | SCL        |
++---+-----------+------------+
+| 3 | GPIO21    | D/C        |
++---+-----------+------------+
+| 4 | GPIO22    | CS         |
++---+-----------+------------+
+| 5 | GPIO23    | SDA        |
++---+-----------+------------+
+| 6 | GPIO25    | SDO        |
++---+-----------+------------+
+| 7 | GPIO5     | Backlight  |
++---+-----------+------------+
+
+
+.. _get-started-esp-wrover-kit-start-development-cmake:
+
+Start Application Development
+-----------------------------
+
+Before powering up the ESP-WROVER-KIT, please make sure that the board has been received in good condition with no obvious signs of damage.
+
+
+Initial Setup
+^^^^^^^^^^^^^
+
+Select the source of power supply for the board by setting jumper JP7. The options are either USB port or an external power supply. For this application selection of USB port is sufficient. Enable UART communication by installing jumpers on JP11. Both selections are shown in table below.
+
++----------------------+----------------------+
+| Power up             | Enable UART          |
+| from USB port        | communication        |
++----------------------+----------------------+
+| |jp7-usb_5v|         | |jp11-rx-tx|         |
++----------------------+----------------------+
+
+Do not install any other jumpers.
+
+
+Now to Development
+^^^^^^^^^^^^^^^^^^
+
+To start development of applications for ESP-WROVER-KIT, proceed to section :doc:`index`, that will walk you through the following steps:
+
+* :ref:`get-started-setup-toolchain-cmake` in your PC to develop applications for ESP32 in C language
+* :ref:`get-started-connect-cmake` the module to the PC and verify if it is accessible
+* :ref:`get-started-build-cmake` for an example application
+* :ref:`get-started-flash-cmake` to run code on the ESP32
+* :ref:`get-started-build-monitor-cmake` instantly what the application is doing
+
+
+Related Documents
+-----------------
+
+* `ESP-WROVER-KIT V3 schematic`_ (PDF)
+* `ESP32 Datasheet <https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf>`_ (PDF)
+* `ESP32-WROVER Datasheet <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_en.pdf>`_ (PDF)
+* `ESP-WROOM-32 Datasheet <https://espressif.com/sites/default/files/documentation/esp-wroom-32_datasheet_en.pdf>`_ (PDF)
+* :doc:`../api-guides/jtag-debugging/index`
+* :doc:`../hw-reference/index`
+
+.. |jp7-ext_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-ext_5v.png
+.. |jp7-usb_5v| image:: ../../_static/esp-wrover-kit-v3-jp7-usb_5v.png
+.. |jp8| image:: ../../_static/esp-wrover-kit-v3-jp8.png
+.. |jp11-rx-tx| image:: ../../_static/esp-wrover-kit-v3-jp11-tx-rx.png
+.. |jp14| image:: ../../_static/esp-wrover-kit-v3-jp14.png
+
+.. _ESP-WROVER-KIT V3 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf
+
+.. toctree::
+    :hidden:
+
+    get-started-wrover-kit-v2.rst
diff --git a/docs/en/get-started-cmake/idf-monitor.rst b/docs/en/get-started-cmake/idf-monitor.rst
new file mode 100644
index 000000000..76bd8b411
--- /dev/null
+++ b/docs/en/get-started-cmake/idf-monitor.rst
@@ -0,0 +1,135 @@
+*******************
+IDF Monitor (CMake)
+*******************
+
+
+The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
+
+It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
+
+Interacting With IDF Monitor
+============================
+
+- ``Ctrl-]`` will exit the monitor.
+- ``Ctrl-T Ctrl-H`` will display a help menu with all other keyboard shortcuts.
+- Any other key apart from ``Ctrl-]`` and ``Ctrl-T`` is sent through the serial port.
+
+Automatically Decoding Addresses
+================================
+
+Any time esp-idf prints a hexadecimal code address of the form ``0x4_______``, IDF Monitor will use addr2line_ to look up the source code location and function name.
+
+.. highlight:: none
+
+When an esp-idf app crashes and panics a register dump and backtrace such as this is produced::
+
+    Guru Meditation Error of type StoreProhibited occurred on core  0. Exception was unhandled.
+    Register dump:
+    PC      : 0x400f360d  PS      : 0x00060330  A0      : 0x800dbf56  A1      : 0x3ffb7e00
+    A2      : 0x3ffb136c  A3      : 0x00000005  A4      : 0x00000000  A5      : 0x00000000
+    A6      : 0x00000000  A7      : 0x00000080  A8      : 0x00000000  A9      : 0x3ffb7dd0
+    A10     : 0x00000003  A11     : 0x00060f23  A12     : 0x00060f20  A13     : 0x3ffba6d0
+    A14     : 0x00000047  A15     : 0x0000000f  SAR     : 0x00000019  EXCCAUSE: 0x0000001d
+    EXCVADDR: 0x00000000  LBEG    : 0x4000c46c  LEND    : 0x4000c477  LCOUNT  : 0x00000000
+
+    Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
+
+IDF Monitor will augment the dump::
+
+    Guru Meditation Error of type StoreProhibited occurred on core  0. Exception was unhandled.
+    Register dump:
+    PC      : 0x400f360d  PS      : 0x00060330  A0      : 0x800dbf56  A1      : 0x3ffb7e00
+    0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
+    (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
+    A2      : 0x3ffb136c  A3      : 0x00000005  A4      : 0x00000000  A5      : 0x00000000
+    A6      : 0x00000000  A7      : 0x00000080  A8      : 0x00000000  A9      : 0x3ffb7dd0
+    A10     : 0x00000003  A11     : 0x00060f23  A12     : 0x00060f20  A13     : 0x3ffba6d0
+    A14     : 0x00000047  A15     : 0x0000000f  SAR     : 0x00000019  EXCCAUSE: 0x0000001d
+    EXCVADDR: 0x00000000  LBEG    : 0x4000c46c  LEND    : 0x4000c477  LCOUNT  : 0x00000000
+
+    Backtrace: 0x400f360d:0x3ffb7e00 0x400dbf56:0x3ffb7e20 0x400dbf5e:0x3ffb7e40 0x400dbf82:0x3ffb7e60 0x400d071d:0x3ffb7e90
+    0x400f360d: do_something_to_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:57
+    (inlined by) inner_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:52
+    0x400dbf56: still_dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:47
+    0x400dbf5e: dont_crash at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:42
+    0x400dbf82: app_main at /home/gus/esp/32/idf/examples/get-started/hello_world/main/./hello_world_main.c:33
+    0x400d071d: main_task at /home/gus/esp/32/idf/components/esp32/./cpu_start.c:254
+
+Behind the scenes, the command IDF Monitor runs to decode each address is::
+
+  xtensa-esp32-elf-addr2line -pfiaC -e build/PROJECT.elf ADDRESS
+
+
+Launch GDB for GDBStub
+======================
+
+By default, if an esp-idf app crashes then the panic handler prints registers and a stack dump as shown above, and then resets.
+
+Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
+
+To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
+
+If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
+
+Behind the scenes, the command IDF Monitor runs is::
+
+  xtensa-esp32-elf-gdb -ex "set serial baud BAUD" -ex "target remote PORT" -ex interrupt build/PROJECT.elf
+
+
+Quick Compile and Flash
+=======================
+
+The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
+
+The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
+
+
+Quick Reset
+===========
+
+The keyboard shortcut ``Ctrl-T Ctrl-R`` will reset the target board via the RTS line (if it is connected.)
+
+
+Pause the Application
+=====================
+
+The keyboard shortcut ``Ctrl-T Ctrl-P`` will reset the target into bootloader, so that the board will run nothing. This is
+useful when you want to wait for another device to startup. Then shortcut ``Ctrl-T Ctrl-R`` can be used to restart the
+application.
+
+
+Toggle Output Display
+=====================
+
+Sometimes you may want to stop new output printed to screen, to see the log before. The keyboard shortcut ``Ctrl-T Ctrl-Y`` will
+toggle the display (discard all serial data when the display is off) so that you can stop to see the log, and revert
+again quickly without quitting the monitor.
+
+
+Simple Monitor
+==============
+
+Earlier versions of ESP-IDF used the pySerial_ command line program miniterm_ as a serial console program.
+
+This program can still be run, via ``make simple_monitor``.
+
+IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
+
+.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
+
+Known Issues with IDF Monitor
+=============================
+
+Issues Observed on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- If you are using the supported Windows environment and receive the error "winpty: command not found" then run ``pacman -S winpty`` to fix.
+- Arrow keys and some other special keys in gdb don't work, due to Windows Console limitations.
+- Occasionally when "make" exits, it may stall for up to 30 seconds before idf_monitor resumes.
+- Occasionally when "gdb" is run, it may stall for a short time before it begins communicating with the gdbstub.
+
+
+.. _addr2line: https://sourceware.org/binutils/docs/binutils/addr2line.html
+.. _gdb: https://sourceware.org/gdb/download/onlinedocs/
+.. _pySerial: https://github.com/pyserial/pyserial
+.. _miniterm: https://pyserial.readthedocs.org/en/latest/tools.html#module-serial.tools.miniterm
diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst
new file mode 100644
index 000000000..faa715c8c
--- /dev/null
+++ b/docs/en/get-started-cmake/index.rst
@@ -0,0 +1,464 @@
+*******************
+Get Started (CMake)
+*******************
+
+.. include:: ../cmake-warning.rst
+
+.. include:: ../cmake-pending-features.rst
+
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+
+Introduction
+============
+
+ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
+
+Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
+
+
+What You Need
+=============
+
+To develop applications for ESP32 you need:
+
+* **PC** loaded with either Windows, Linux or Mac operating system
+* **Toolchain** to compile code for ESP32
+* **Build tools** CMake and Ninja to build a full **Application** for ESP32
+* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
+* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
+* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
+
+.. figure:: ../../_static/what-you-need-cmake.png
+    :align: center
+    :alt: Development of applications for ESP32
+    :figclass: align-center
+
+    Development of applications for ESP32
+
+Steps to set up Development Environment:
+
+1. Setup of **Toolchain**
+2. Getting **ESP-IDF** from GitHub
+
+Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
+
+1. Configuration of a **Project** and writing the code
+2. Compilation of the **Project** and linking it to build an **Application**
+3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
+4. Monitoring / debugging of the **Application** output via USB/serial
+
+
+Development Board Guides
+========================
+
+If you have one of ESP32 development boards listed below, click on the link for hardware setup:
+
+.. toctree::
+    :maxdepth: 1
+
+    ESP32 DevKitC <get-started-devkitc>
+    ESP-WROVER-KIT <get-started-wrover-kit>
+    ESP32-PICO-KIT <get-started-pico-kit>
+
+If you have different board, move to sections below.
+
+
+.. _get-started-setup-toolchain-cmake:
+
+Setup Toolchain
+===============
+
+The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions. 
+
+.. toctree::
+    :hidden:
+
+    Windows <windows-setup>
+    Linux <linux-setup> 
+    MacOS <macos-setup> 
+
++-------------------+-------------------+-------------------+
+| |windows-logo|    | |linux-logo|      | |macos-logo|      |
++-------------------+-------------------+-------------------+
+| `Windows`_        | `Linux`_          | `Mac OS`_         |
++-------------------+-------------------+-------------------+
+
+.. |windows-logo| image:: ../../_static/windows-logo.png
+    :target: ../get-started-cmake/windows-setup.html
+
+.. |linux-logo| image:: ../../_static/linux-logo.png
+    :target: ../get-started-cmake/linux-setup.html
+
+.. |macos-logo| image:: ../../_static/macos-logo.png
+    :target: ../get-started-cmake/macos-setup.html
+
+.. _Windows: ../get-started-cmake/windows-setup.html
+.. _Linux: ../get-started-cmake/linux-setup.html
+.. _Mac OS: ../get-started-cmake/macos-setup.html
+
+.. note::
+
+    We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and MacOS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
+
+Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup-cmake`.
+
+Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf-cmake`.
+
+.. _get-started-get-esp-idf-cmake:
+
+Get ESP-IDF
+===========
+
+Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command.
+
+Linux and MacOS
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    mkdir -p ~/esp
+    cd ~/esp
+    git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
+
+ESP-IDF will be downloaded into ``~/esp/esp-idf``.
+
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: batch
+
+    mkdir %userprofile%\esp
+    cd %userprofile%\esp
+    git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
+
+.. highlight:: bash
+.. note::
+
+    Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
+
+        cd esp-idf
+        git submodule update --init
+
+.. note::
+
+   The CMake-based build system preview uses a different Git branch to the default. This branch is ``feature/cmake``. If you missed the ``--branch`` option when cloning then you can switch branches on the command line::
+
+         cd esp-idf
+         git checkout feature/cmake
+
+.. _get-started-setup-path-cmake:
+
+Setup Environment Variables
+===========================
+
+ESP-IDF requires two environment variables to be set for normal operation:
+
+- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
+- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
+
+These two variables should be set up on your PC, otherwise projects will not build.
+
+Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows-cmake>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos-cmake>` in section :doc:`add-idf_path-to-profile`.
+
+.. _get-started-start-project-cmake:
+
+Start a Project
+===============
+
+Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
+
+Copy :example:`get-started/hello_world` to ``~/esp`` directory:
+
+Linux and MacOS
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    cd ~/esp
+    cp -r $IDF_PATH/examples/get-started/hello_world .
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: batch
+
+    cd %userprofile%\esp
+    xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
+
+You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
+
+It is also possible to build examples in-place, without copying them first.
+
+.. important::
+
+    The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
+
+.. _get-started-connect-cmake:
+
+Connect
+=======
+
+You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
+
+.. _get-started-configure-cmake:
+
+Configure
+=========
+
+Naviagate to the directory of the ``hello_world`` application copy, and run the ``menuconfig`` project configuration utility:
+
+Linux and MacOS
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    cd ~/esp/hello_world
+    idf.py menuconfig
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: batch
+
+    cd %userprofile%\esp\hello_world
+    idf.py menuconfig
+
+.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path-cmake`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf-cmake`.
+
+.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work (it opens the file in Visual Studio instead). You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
+
+.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
+
+If previous steps have been done correctly, the following menu will be displayed:
+
+.. figure:: ../../_static/project-configuration.png
+    :align: center
+    :alt: Project configuration - Home window
+    :figclass: align-center
+
+    Project configuration - Home window
+
+Here are couple of tips on navigation and use of ``menuconfig``:
+
+* Use up & down arrow keys to navigate the menu.
+* Use Enter key to go into a submenu, Escape key to go up a level or exit.
+* Type ``?`` to see a help screen. Enter key exits the help screen.
+* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
+* Pressing ``?`` while highlighting a configuration item displays help about that item.
+* Type ``/`` to search the configuration items.
+
+.. _get-started-build-cmake:
+
+Build The Project
+=================
+
+.. highlight:: bash
+
+Now you can build the project. Run::
+
+    idf.py build
+
+This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
+
+.. code-block:: none
+
+   $ idf.py build
+   Running cmake in directory /path/to/hello_world/build
+   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
+   Warn about uninitialized values.
+   -- Found Git: /usr/bin/git (found version "2.17.0")
+   -- Building empty aws_iot component due to configuration
+   -- Component names: ...
+   -- Component paths: ...
+   
+   ... (more lines of build system output)
+   
+   [527/527] Generating hello-world.bin
+   esptool.py v2.3.1
+   
+   Project build complete. To flash, run this command:
+   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
+   or run 'idf.py -p PORT flash'
+
+If there are no errors, the build will finish by generating the firmware binary .bin file.
+
+.. _get-started-flash-cmake:
+
+Flash To A Device
+=================
+
+Now you can flash the application to the ESP32 board. Run::
+
+    idf.py -p PORT flash
+
+Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. See :doc:`establish-serial-connection` for full details.
+
+This step will flash the binaries that you just built to your ESP32 board.
+
+.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
+
+.. code-block:: none
+
+    Running esptool.py in directory [...]/esp/hello_world
+    Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
+    esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
+    esptool.py v2.3.1
+    Connecting....
+    Detecting chip type... ESP32
+    Chip is ESP32D0WDQ6 (revision 1)
+    Features: WiFi, BT, Dual Core
+    Uploading stub...
+    Running stub...
+    Stub running...
+    Changing baud rate to 460800
+    Changed.
+    Configuring flash size...
+    Auto-detected Flash size: 4MB
+    Flash params set to 0x0220
+    Compressed 22992 bytes to 13019...
+    Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
+    Hash of data verified.
+    Compressed 3072 bytes to 82...
+    Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
+    Hash of data verified.
+    Compressed 136672 bytes to 67544...
+    Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
+    Hash of data verified.
+    
+    Leaving...
+    Hard resetting via RTS pin...
+
+If there are no issues, at the end of flash process, the module will be reset and “hello_world” application will be running there.
+
+.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
+
+
+.. _get-started-build-monitor-cmake:
+
+Monitor
+=======
+
+To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
+
+    $ idf.py -p /dev/ttyUSB0 monitor
+    Running idf_monitor in directory [...]/esp/hello_world/build
+    Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
+    --- idf_monitor on /dev/ttyUSB0 115200 ---
+    --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+    ets Jun  8 2016 00:22:57
+
+    rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+    ets Jun  8 2016 00:22:57
+    ...
+
+Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application.
+
+.. code-block:: none
+
+    ...
+    Hello world!
+    Restarting in 10 seconds...
+    I (211) cpu_start: Starting scheduler on APP CPU.
+    Restarting in 9 seconds...
+    Restarting in 8 seconds...
+    Restarting in 7 seconds...
+
+To exit the monitor use shortcut ``Ctrl+]``.
+
+.. note::
+
+    If instead of the messages above, you see a random garbage similar to::
+
+        e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
+        ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
+
+    or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure-cmake>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-flash-cmake>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+
+.. note::
+
+   You can combine building, flashing and monitoring into one step as follows::
+
+       idf.py -p PORT flash monitor
+
+Check the section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
+
+Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
+
+That's all what you need to get started with ESP32!
+
+Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
+
+
+Updating ESP-IDF
+================
+
+After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf-cmake`.
+
+Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands:
+
+Linux and MacOS
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    cd ~/esp/esp-idf
+    git pull
+    git submodule update --init --recursive
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: batch
+
+    cd %userprofile%\esp\esp-idf
+    git pull
+    git submodule update --init --recursive
+
+The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
+
+.. highlight:: bash
+
+It is also possible to check out a specific release of ESP-IDF, e.g. `v2.1`.
+
+Linux and MacOS
+~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+    cd ~/esp
+    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
+    cd esp-idf-v2.1/
+    git checkout v2.1
+    git submodule update --init --recursive
+
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: batch
+
+    cd %userprofile%\esp
+    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
+    cd esp-idf-v2.1/
+    git checkout v2.1
+    git submodule update --init --recursive
+
+After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
+
+.. note::
+
+   Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
+
+
+Related Documents
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    add-idf_path-to-profile
+    establish-serial-connection
+    eclipse-setup
+    idf-monitor
+    toolchain-setup-scratch
diff --git a/docs/en/get-started-cmake/linux-setup-scratch.rst b/docs/en/get-started-cmake/linux-setup-scratch.rst
new file mode 100644
index 000000000..e1d2205d8
--- /dev/null
+++ b/docs/en/get-started-cmake/linux-setup-scratch.rst
@@ -0,0 +1,73 @@
+******************************************
+Setup Linux Toolchain from Scratch (CMake)
+******************************************
+
+.. include:: ../cmake-warning.rst
+
+The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
+
+Install Prerequisites
+=====================
+
+To compile with ESP-IDF you need to get the following packages:
+
+- CentOS 7::
+
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
+
+- Ubuntu and Debian::
+
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
+
+- Arch::
+
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
+
+.. note::
+    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
+
+Compile the Toolchain from Source
+=================================
+
+- Install dependencies:
+
+  - CentOS 7::
+
+        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
+
+  - Ubuntu pre-16.04::
+
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
+
+  - Ubuntu 16.04::
+
+        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+
+  - Debian 9::
+
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+
+  - Arch::
+
+        TODO
+
+Download ``crosstool-NG`` and build it::
+
+    cd ~/esp
+    git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
+    cd crosstool-NG
+    ./bootstrap && ./configure --enable-local && make install
+
+Build the toolchain::
+
+    ./ct-ng xtensa-esp32-elf
+    ./ct-ng build
+    chmod -R u+w builds/xtensa-esp32-elf
+
+Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path-cmake>` to add the toolchain to your ``PATH``.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
diff --git a/docs/en/get-started-cmake/linux-setup.rst b/docs/en/get-started-cmake/linux-setup.rst
new file mode 100644
index 000000000..8977a582b
--- /dev/null
+++ b/docs/en/get-started-cmake/linux-setup.rst
@@ -0,0 +1,112 @@
+*********************************************
+Standard Setup of Toolchain for Linux (CMake)
+*********************************************
+
+.. include:: ../cmake-warning.rst
+
+Install Prerequisites
+=====================
+
+To compile with ESP-IDF you need to get the following packages:
+
+- CentOS 7::
+
+    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
+
+- Ubuntu and Debian::
+
+    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
+
+- Arch::
+
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
+
+.. note::
+    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".
+
+Toolchain Setup
+===============
+
+ESP32 toolchain for Linux is available for download from Espressif website:
+
+- for 64-bit Linux:
+
+  https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+- for 32-bit Linux:
+
+  https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+1.  Download this file, then extract it in ``~/esp`` directory::
+
+        mkdir -p ~/esp
+        cd ~/esp
+        tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+.. _setup-linux-toolchain-add-it-to-path-cmake:
+
+2.  The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
+
+    To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
+
+        export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+    Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
+
+        alias get_esp32='export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
+
+    Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
+
+    .. note::
+
+        If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
+
+3.  Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
+
+        printenv PATH
+
+    You are looking for similar result containing toolchain's path at the end of displayed string::
+
+        $ printenv PATH
+        /home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
+
+    Instead of ``/home/user-name`` there should be a home path specific to your installation.
+
+
+Permission issues /dev/ttyUSB0
+------------------------------
+
+With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group-cmake>`.
+
+
+Arch Linux Users
+----------------
+
+To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
+
+Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
+
+- https://aur.archlinux.org/packages/ncurses5-compat-libs/
+- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
+
+Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
+
+Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+
+Related Documents
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    linux-setup-scratch
+
+
+.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
diff --git a/docs/en/get-started-cmake/macos-setup-scratch.rst b/docs/en/get-started-cmake/macos-setup-scratch.rst
new file mode 100644
index 000000000..ae6e8c43e
--- /dev/null
+++ b/docs/en/get-started-cmake/macos-setup-scratch.rst
@@ -0,0 +1,83 @@
+***********************************************
+Setup Toolchain for Mac OS from Scratch (CMake)
+***********************************************
+
+.. include:: ../cmake-warning.rst
+
+Package Manager
+===============
+
+To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or homebrew_ package manager.
+
+MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
+
+    .. _homebrew: https://brew.sh/
+    .. _MacPorts: https://www.macports.org/install.php
+
+Install Prerequisites
+=====================
+
+- install pip::
+
+    sudo easy_install pip
+
+- install pyserial::
+
+    sudo pip install pyserial
+
+- install CMake & Ninja build:
+
+  - If you have HomeBrew, you can run::
+
+      brew install cmake ninja
+
+  - If you have MacPorts, you can run::
+
+      sudo port install cmake ninja
+
+Compile the Toolchain from Source
+=================================
+
+- Install dependencies:
+
+  - with MacPorts::
+
+        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
+
+  - with homebrew::
+
+        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
+
+Create a case-sensitive filesystem image::
+
+    hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
+
+Mount it::
+
+    hdiutil mount ~/esp/crosstool.dmg
+
+Create a symlink to your work directory::
+
+    cd ~/esp
+    ln -s /Volumes/ctng crosstool-NG
+
+Download ``crosstool-NG`` and build it::
+
+    cd ~/esp
+    git clone -b xtensa-1.22.x https://github.com/espressif/crosstool-NG.git
+    cd crosstool-NG
+    ./bootstrap && ./configure --enable-local && make install
+
+Build the toolchain::
+
+    ./ct-ng xtensa-esp32-elf
+    ./ct-ng build
+    chmod -R u+w builds/xtensa-esp32-elf
+
+Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path-cmake>` to add the toolchain to your ``PATH``.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
diff --git a/docs/en/get-started-cmake/macos-setup.rst b/docs/en/get-started-cmake/macos-setup.rst
new file mode 100644
index 000000000..21a780c52
--- /dev/null
+++ b/docs/en/get-started-cmake/macos-setup.rst
@@ -0,0 +1,90 @@
+**********************************************
+Standard Setup of Toolchain for Mac OS (CMake)
+**********************************************
+
+.. include:: ../cmake-warning.rst
+
+Install Prerequisites
+=====================
+
+ESP-IDF will use the version of Python installed by default on Mac OS.
+
+- install pip::
+
+    sudo easy_install pip
+
+- install pyserial::
+
+    sudo pip install pyserial
+
+- install CMake & Ninja build:
+
+  - If you have HomeBrew_, you can run::
+
+      brew install cmake ninja
+
+  - If you have MacPorts_, you can run::
+
+      sudo port install cmake ninja
+
+  - Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation downloads.
+
+- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
+
+.. note::
+   If an error like this is shown during any step::
+
+     xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
+
+    Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
+
+Toolchain Setup
+===============
+
+ESP32 toolchain for macOS is available for download from Espressif website:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+Download this file, then extract it in ``~/esp`` directory::
+
+    mkdir -p ~/esp
+    cd ~/esp
+    tar -xzf ~/Downloads/xtensa-esp32-elf-osx-1.22.0-80-g6c4433a-5.2.0.tar.gz
+
+.. _setup-macos-toolchain-add-it-to-path-cmake:
+
+The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
+
+To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
+
+    export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin
+
+Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
+
+    alias get_esp32="export PATH=$PATH:$HOME/esp/xtensa-esp32-elf/bin"
+
+Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
+
+Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
+
+        printenv PATH
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+Related Documents
+=================
+
+.. toctree::
+    :maxdepth: 1
+
+    macos-setup-scratch
+
+.. _cmake: https://cmake.org/
+.. _ninja: https://ninja-build.org/
+.. _ccache: https://ccache.samba.org/
+.. _homebrew: https://brew.sh/
+.. _MacPorts: https://www.macports.org/install.php
diff --git a/docs/en/get-started-cmake/toolchain-setup-scratch.rst b/docs/en/get-started-cmake/toolchain-setup-scratch.rst
new file mode 100644
index 000000000..b5e9f0fbd
--- /dev/null
+++ b/docs/en/get-started-cmake/toolchain-setup-scratch.rst
@@ -0,0 +1,25 @@
+.. _get-started-customized-setup-cmake:
+
+*************************************
+Customized Setup of Toolchain (CMake)
+*************************************
+
+Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain-cmake`) you may build the toolchain yourself.
+
+If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:
+
+- if you want to customize toolchain build configuration
+- if you want to use a different GCC version (such as 4.8.5)
+- if you want to hack gcc or newlib or libstdc++
+- if you are curious and/or have time to spare
+- if you don't trust binaries downloaded from the Internet
+
+In any case, here are the instructions to compile the toolchain yourself.
+
+.. toctree::
+    :maxdepth: 1
+
+    windows-setup-scratch
+    linux-setup-scratch
+    macos-setup-scratch
+
diff --git a/docs/en/get-started-cmake/windows-setup-scratch.rst b/docs/en/get-started-cmake/windows-setup-scratch.rst
new file mode 100644
index 000000000..d8381ae68
--- /dev/null
+++ b/docs/en/get-started-cmake/windows-setup-scratch.rst
@@ -0,0 +1,89 @@
+********************************************
+Setup Windows Toolchain from Scratch (CMake)
+********************************************
+
+.. include:: ../cmake-warning.rst
+
+This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
+
+To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
+
+
+.. note::
+   The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
+
+Tools
+=====
+
+cmake
+^^^^^
+
+Download the latest stable release of CMake_ for Windows and run the installer.
+
+When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
+
+Ninja build
+^^^^^^^^^^^
+
+.. note::
+    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
+
+Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
+
+The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_ (or you can choose a directory which is already on your Path).
+
+
+Python 2.x
+^^^^^^^^^^
+
+Download the latest Python_ 2.7 for Windows installer, and run it.
+
+The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
+
+Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
+
+  pip install pyserial
+
+MConf for IDF
+^^^^^^^^^^^^^
+
+Download the configuration tool mconf-idf from the `kconfig-frontends releases page <mconf-idf>`_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF.
+
+This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
+
+Toolchain Setup
+===============
+
+Download the precompiled Windows toolchain from dl.espressif.com:
+
+https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
+
+Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
+
+Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
+
+.. note::
+   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
+
+
+.. _add-directory-windows-path-cmake:
+
+Adding Directory to Path
+========================
+
+To add any new directory to your Windows Path environment variable:
+
+Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
+
+Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
+
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+.. _ninja: https://ninja-build.org/
+.. _Python: https://www.python.org/downloads/windows/
+.. _MSYS2: https://msys2.github.io/
+
diff --git a/docs/en/get-started-cmake/windows-setup.rst b/docs/en/get-started-cmake/windows-setup.rst
new file mode 100644
index 000000000..c7393c8b9
--- /dev/null
+++ b/docs/en/get-started-cmake/windows-setup.rst
@@ -0,0 +1,71 @@
+***********************************************
+Standard Setup of Toolchain for Windows (CMake)
+***********************************************
+
+.. include:: ../cmake-warning.rst
+
+.. note::
+      The CMake-based build system is only supported on 64-bit versions of Windows.
+
+Introduction
+============
+
+ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
+
+For this Getting Started we're going to use a command prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
+
+.. note::
+   The GNU Make based build system requires the MSYS2_ Unix compatibility environment on Windows. The CMake-based build system does not require this environment.
+
+ESP-IDF Tools Installer
+=======================
+
+The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
+
+https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe
+
+The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
+
+By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
+
+Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
+
+Installing Git
+==============
+
+The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
+
+If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
+
+Using a Terminal
+================
+
+For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
+
+- You can use the built-in Windows Command Prompt, under the Start menu. All Windows command line instructions in this documentation are "batch" commands for use with the Windows Command Prompt.
+- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as is given for Mac OS or Linux. You can find it in the Start menu once installed.
+- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
+
+Next Steps
+==========
+
+To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf-cmake`.
+
+Related Documents
+=================
+
+For advanced users who want to customize the install process:
+
+.. toctree::
+    :maxdepth: 1
+
+    windows-setup-scratch
+
+
+.. _MSYS2: https://msys2.github.io/
+.. _cmake: https://cmake.org/download/
+.. _ninja: https://ninja-build.org/
+.. _Python: https://www.python.org/downloads/windows/
+.. _Git for Windows: https://gitforwindows.org/
+.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
+.. _Github Desktop: https://desktop.github.com/
diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst
index 3529c86d0..8ce9a9ae6 100644
--- a/docs/en/get-started/add-idf_path-to-profile.rst
+++ b/docs/en/get-started/add-idf_path-to-profile.rst
@@ -1,40 +1,40 @@
-Add IDF_PATH & idf.py PATH to User Profile
-==========================================
-
+Add IDF_PATH to User Profile
+============================
 :link_to_translation:`zh_CN:[中文]`
 
+To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
 
-To use the CMake-based build system and the idf.py tool, two modifications need to be made to system environment variables:
-
-- ``IDF_PATH`` needs to be set to the path of the directory containing ESP-IDF.
-- System ``PATH`` variable to include the directory containing the ``idf.py`` tool (part of ESP-IDF).
-
-To preserve setting of these variables between system restarts, add them to the user profile by following the instructions below.
-
-.. note:: If using an IDE, you can optionally set these environment variables in your IDE's project environment rather than from the command line as described below.
-
-.. note:: If you don't ever use the command line ``idf.py`` tool, but run cmake directly or via an IDE, then it is not necessary to set the ``PATH`` variable - only ``IDF_PATH``. However it can be useful to set both.
-
-.. note:: If you only ever use the command line ``idf.py`` tool, and never use cmake directly or via an IDE, then it is not necessary to set the ``IDF_PATH`` variable - ``idf.py`` will detect the directory it is contained within and set ``IDF_PATH`` appropriately if it is missing.
-
-.. _add-paths-to-profile-windows:
+.. _add-idf_path-to-profile-windows:
 
 Windows
 -------
 
-To edit Environment Variables on Windows 10, search for "Edit Environment Variables" under the Start menu.
+The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
 
-On earlier Windows versions, open the System Control Panel then choose "Advanced" and look for the Environment Variables button.
+#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
 
-You can set these environment variables for all users, or only for the current user, depending on whether other users of your computer will be using ESP-IDF.
+#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
 
-- Click ``New...`` to add a new environment variable named ``IDF_PATH``. Set the path to directory containing ESP-IDF, for example ``C:\Users\myuser\esp\esp-idf``.
-- Locate the ``Path`` environment variable and double-click to edit it. Append the following to the end: ``;%IDF_PATH%\tools``. This will allow you to run ``idf.py`` and other tools from Windows Command Prompt.
+#. Add the ``export`` command to the script file, e.g.::
 
-If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
+       export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
+
+   Remember to replace back-slashes with forward-slashes in the original Windows path.
+
+#. Save the script file.
+
+#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
+
+       printenv IDF_PATH
+
+   The path previusly entered in the script file should be printed out.
+
+If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
+
+    export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
+
+If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`. 
 
 
 .. _add-idf_path-to-profile-linux-macos:
@@ -42,20 +42,15 @@ If you got here from section :ref:`get-started-setup-path`, while installing s/w
 Linux and MacOS
 ---------------
 
-Set up ``IDF_PATH`` and add ``idf.py`` to the PATH by adding the following two lines to your ``~/.profile`` file::
+Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
 
     export IDF_PATH=~/esp/esp-idf
-    export PATH="$PATH:$IDF_PATH/tools"
+
+Log off and log in back to make this change effective. 
 
 .. note::
 
-   ``~/.profile`` means a file named ``.profile`` in your user's home directory (which is abbreviated ``~`` in the shell).
-
-Log off and log in back to make this change effective.
-
-.. note::
-
-    Not all shells use ``.profile``. If you have ``/bin/bash`` and ``.bash_profile`` exists then update this file instead. For ``zsh``, update ``.zprofile``. Other shells may use other profile files (consult the shell's documentation).
+    If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
 
 Run the following command to check if ``IDF_PATH`` is set::
 
@@ -63,15 +58,8 @@ Run the following command to check if ``IDF_PATH`` is set::
 
 The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
 
-To verify idf.py is now on the ``PATH``, you can run the following::
-
-  which idf.py
-
-A path like ``${IDF_PATH}/tools/idf.py`` should be printed.
-
-If you do not like to have ``IDF_PATH`` or ``PATH`` modifications set, you can enter it manually in terminal window on each restart or logout::
+If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
 
     export IDF_PATH=~/esp/esp-idf
-    export PATH="$PATH:$IDF_PATH/tools"
 
 If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
diff --git a/docs/en/get-started/eclipse-setup-windows.rst b/docs/en/get-started/eclipse-setup-windows.rst
new file mode 100644
index 000000000..62373485a
--- /dev/null
+++ b/docs/en/get-started/eclipse-setup-windows.rst
@@ -0,0 +1,79 @@
+**********************
+Eclipse IDE on Windows
+**********************
+:link_to_translation:`zh_CN:[中文]`
+
+Configuring Eclipse on Windows requires some different steps. The full configuration steps for Windows are shown below.
+
+(For OS X and Linux instructions, see the :doc:`Eclipse IDE page <eclipse-setup>`.)
+
+Installing Eclipse IDE
+======================
+
+Follow the steps under :ref:`Installing Eclipse IDE <eclipse-install-steps>` for all platforms.
+
+.. _eclipse-windows-setup:
+
+Setting up Eclipse on Windows
+=============================
+
+Once your new Eclipse installation launches, follow these steps:
+
+Import New Project
+------------------
+
+* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
+
+* Once Eclipse is running, choose File -> Import...
+
+* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
+
+* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
+
+* On the same page, under "Toolchain for Indexer Settings" uncheck "Show only available toolchains that support this platform".
+
+* On the extended list that appears, choose "Cygwin GCC". Then click Finish.
+
+*Note: you may see warnings in the UI that Cygwin GCC Toolchain could not be found. This is OK, we're going to reconfigure Eclipse to find our toolchain.*
+
+Project Properties
+------------------
+
+* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
+
+* Click on the "C/C++ Build" properties page (top-level):
+
+  * Uncheck "Use default build command" and enter this for the custom build command: ``python ${IDF_PATH}/tools/windows/eclipse_make.py``.
+
+* Click on the "Environment" properties page under "C/C++ Build":
+
+  * Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
+
+  * Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. The IDF_PATH directory should be specified using forwards slashes not backslashes, ie *C:/Users/user-name/Development/esp-idf*.
+
+  * Edit the PATH environment variable. Delete the existing value and replace it with ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (If you installed msys32 to a different directory then you'll need to change these paths to match).
+
+* Click on "C/C++ General" -> "Preprocessor Include Paths, Macros, etc." property page:
+
+  * Click the "Providers" tab
+
+     * In the list of providers, click "CDT GCC Built-in Compiler Settings Cygwin". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
+
+     * In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern, and wrap remaining part with brackets. This means the full Compiler command pattern should be ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``
+
+
+Building in Eclipse
+-------------------
+
+Continue from :ref:`Building in Eclipse <eclipse-build-project>` for all platforms.
+
+Technical Details
+=================
+
+**Of interest to Windows gurus or very curious parties, only.**
+
+Explanations of the technical reasons for some of these steps. You don't need to know this to use esp-idf with Eclipse on Windows, but it may be helpful background knowledge if you plan to do dig into the Eclipse support:
+
+* The xtensa-esp32-elf-gcc cross-compiler is *not* a Cygwin toolchain, even though we tell Eclipse that it is one. This is because msys2 uses Cygwin and supports Unix-style paths (of the type ``/c/blah`` instead of ``c:/blah`` or ``c:\\blah``). In particular, xtensa-esp32-elf-gcc reports to the Eclipse "built-in compiler settings" function that its built-in include directories are all under ``/usr/``, which is a Unix/Cygwin-style path that Eclipse otherwise can't resolve. By telling Eclipse the compiler is Cygwin, it resolves these paths internally using the ``cygpath`` utility.
+
+* The same problem occurs when parsing make output from esp-idf. Eclipse parses this output to find header directories, but it can't resolve include directories of the form ``/c/blah`` without using ``cygpath``. There is a heuristic that Eclipse Build Output Parser uses to determine whether it should call ``cygpath``, but for currently unknown reasons the esp-idf configuration doesn't trigger it. For this reason, the ``eclipse_make.py`` wrapper script is used to call ``make`` and then use ``cygpath`` to process the output for Eclipse.
diff --git a/docs/en/get-started/eclipse-setup.rst b/docs/en/get-started/eclipse-setup.rst
index 5d20efc3a..7d17d6c15 100644
--- a/docs/en/get-started/eclipse-setup.rst
+++ b/docs/en/get-started/eclipse-setup.rst
@@ -3,10 +3,108 @@ Build and Flash with Eclipse IDE
 ********************************
 :link_to_translation:`zh_CN:[中文]`
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may enocunter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+.. _eclipse-install-steps:
+
+Installing Eclipse IDE
+======================
+
+The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
+
+* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
+
+* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
+
+* Download the Eclipse Installer for your platform from eclipse.org_.
+
+* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
+
+Windows Users
+=============
+
+Using ESP-IDF with Eclipse on Windows requires different configuration steps. :ref:`See the Eclipse IDE on Windows guide <eclipse-windows-setup>`.
+
+Setting up Eclipse
+==================
+
+Once your new Eclipse installation launches, follow these steps:
+
+Import New Project
+------------------
+
+* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
+
+* Once Eclipse is running, choose File -> Import...
+
+* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
+
+* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
+
+* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
+
+
+Project Properties
+------------------
+
+* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
+
+* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
+
+* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed.
+
+* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path.
+
+* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
+
+Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
+
+* Click the "Providers" tab
+
+* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Under "Command to get compiler specs", replace the text ``${COMMAND}`` at the beginning of the line with ``xtensa-esp32-elf-gcc``. This means the full "Command to get compiler specs" should be ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``.
+
+* In the list of providers, click "CDT GCC Build Output Parser" and type ``xtensa-esp32-elf-`` at the beginning of the Compiler command pattern. This means the full Compiler command pattern should be ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``
+
+.. _eclipse-build-project:
+
+Building in Eclipse
+-------------------
+
+Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
+
+* Click OK to close the Properties dialog in Eclipse.
+
+* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
+
+*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
+
+* Back in Eclipse, choose Project -> Build to build your project.
+
+**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
+
+Flash from Eclipse
+------------------
+
+You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
+
+* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
+
+* Select Build Targets -> Create... from the context menu.
+
+* Type "flash" as the target name. Leave the other options as their defaults.
+
+* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
+
+Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
+
+Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
+
+Related Documents
+-----------------
+
+.. toctree::
+    :maxdepth: 1
+
+    eclipse-setup-windows
 
-Documentation for Eclipse setup with CMake-based build system and Eclipse CDT is coming soon.
 
 .. _eclipse.org: https://www.eclipse.org/
 
diff --git a/docs/en/get-started/establish-serial-connection.rst b/docs/en/get-started/establish-serial-connection.rst
index 3566e8551..e54345d83 100644
--- a/docs/en/get-started/establish-serial-connection.rst
+++ b/docs/en/get-started/establish-serial-connection.rst
@@ -55,8 +55,6 @@ MacOS ::
     ls /dev/cu.*
 
 
-.. note: MacOS users: if you don't see the serial port then check you have the USB/serial drivers installed as shown in the Getting Started guide for your particular development board. For MacOS High Sierra (10.13), you may also have to explicitly allow the drivers to load. Open System Preferences -> Security & Privacy -> General and check if there is a message shown here about "System Software from developer ..." where the developer name is Silicon Labs or FTDI.
-
 .. _linux-dialout-group:
 
 Adding user to ``dialout`` on Linux
@@ -128,4 +126,5 @@ If you see some legible log, it means serial connection is working and you are r
 
 If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
 
+
 .. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
diff --git a/docs/en/get-started/idf-monitor.rst b/docs/en/get-started/idf-monitor.rst
index c54ed4314..09291a3d3 100644
--- a/docs/en/get-started/idf-monitor.rst
+++ b/docs/en/get-started/idf-monitor.rst
@@ -3,7 +3,7 @@ IDF Monitor
 ***********
 :link_to_translation:`zh_CN:[中文]`
 
-The idf_monitor tool is a Python program which runs when the ``idf.py monitor`` target is invoked in IDF.
+The IDF Monitor tool is a Python program which runs when the ``make monitor`` target is invoked in IDF.
 
 It is mainly a serial terminal program which relays serial data to and from the target device's serial port, but it has some other IDF-specific features.
 
@@ -67,7 +67,7 @@ By default, if an esp-idf app crashes then the panic handler prints registers an
 
 Optionally, the panic handler can be configured to run a serial "gdb stub" which can communicate with a gdb_ debugger program and allow memory to be read, variables and stack frames examined, etc. This is not as versatile as JTAG debugging, but no special hardware is required.
 
-To enable the gdbstub, run ``idf.py menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
+To enable the gdbstub, run ``make menuconfig`` and set :ref:`CONFIG_ESP32_PANIC` option to ``Invoke GDBStub``.
 
 If this option is enabled and IDF Monitor sees the gdb stub has loaded, it will automatically pause serial monitoring and run GDB with the correct arguments. After GDB exits, the board will be reset via the RTS serial line (if this is connected.)
 
@@ -79,9 +79,9 @@ Behind the scenes, the command IDF Monitor runs is::
 Quick Compile and Flash
 =======================
 
-The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause idf_monitor, run the ``idf.py flash`` target, then resume idf_monitor. Any changed source files will be recompiled before re-flashing.
+The keyboard shortcut ``Ctrl-T Ctrl-F`` will pause IDF Monitor, run the ``make flash`` target, then resume IDF Monitor. Any changed source files will be recompiled before re-flashing.
 
-The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause idf-monitor, run the ``idf.py app-flash`` target, then resume idf_monitor. This is similar to ``idf.py flash``, but only the main app is compiled and reflashed.
+The keyboard shortcut ``Ctrl-T Ctrl-A`` will pause IDF Monitor, run the ``make app-flash`` target, then resume IDF Monitor. This is similar to ``make flash``, but only the main app is compiled and reflashed.
 
 
 Quick Reset
@@ -115,7 +115,6 @@ This program can still be run, via ``make simple_monitor``.
 
 IDF Monitor is based on miniterm and shares the same basic keyboard shortcuts.
 
-.. note:: This target only works in the GNU Make based build system, not the CMake-based build system preview.
 
 Known Issues with IDF Monitor
 =============================
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index 431c097cf..9e33e6349 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -3,10 +3,7 @@ Get Started
 ***********
 :link_to_translation:`zh_CN:[中文]`
 
-This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
-
-.. note::
-   The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards. 
 
 
 Introduction
@@ -23,8 +20,7 @@ What You Need
 To develop applications for ESP32 you need:
 
 * **PC** loaded with either Windows, Linux or Mac operating system
-* **Toolchain** to compile code for ESP32
-* **Build tools** CMake and Ninja to build a full **Application** for ESP32
+* **Toolchain** to build the **Application** for ESP32
 * **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
 * A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
 * The **ESP32** board itself and a **USB cable** to connect it to the **PC**
@@ -36,23 +32,28 @@ To develop applications for ESP32 you need:
 
     Development of applications for ESP32
 
-Development Environment Steps:
+Preparation of development environment consists of three steps:
 
 1. Setup of **Toolchain**
-2. Getting **ESP-IDF** from GitHub
+2. Getting of **ESP-IDF** from GitHub
+3. Installation and configuration of **Eclipse**
 
-Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
+You may skip the last step, if you prefer to use different editor.
+
+Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
 
 1. Configuration of a **Project** and writing the code
 2. Compilation of the **Project** and linking it to build an **Application**
-3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
-4. Monitoring / debugging of the **Application** output via USB/serial
+3. Flashing (uploading) of the **Application** to **ESP32**
+4. Monitoring / debugging of the **Application**
+
+See instructions below that will walk you through these steps.
 
 
-Development Board Guides
-========================
+Guides
+======
 
-If you have one of ESP32 development boards listed below, click on the link for hardware setup:
+If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
 
 .. toctree::
     :maxdepth: 1
@@ -99,12 +100,13 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
 
 .. note::
 
-    We are an using ``esp`` subdirectory in your user's home directory (``~/esp`` on Linux and Mac OS, ``%userprofile%\esp`` on Windows) to install everything needed for ESP-IDF. You can use any different directory, but will need to adjust the respective commands.
+    We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
 
 Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
 
 Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
 
+
 .. _get-started-get-esp-idf:
 
 Get ESP-IDF
@@ -114,48 +116,26 @@ Get ESP-IDF
 
 Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
 
-    mkdir -p ~/esp
     cd ~/esp
     git clone --recursive https://github.com/espressif/esp-idf.git
 
 ESP-IDF will be downloaded into ``~/esp/esp-idf``.
 
-.. highlight:: batch
-
-For **Windows Command Prompt** users, the equivalent commands are::
-
-    mkdir %userprofile%\esp
-    cd %userprofile%\esp
-    git clone --branch feature/cmake --recursive https://github.com/espressif/esp-idf.git
-
-.. highlight:: bash
 .. note::
 
     Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
 
-        cd esp-idf
+        cd ~/esp/esp-idf
         git submodule update --init
 
-.. note::
-
-   The CMake-based build system preview uses a different Git branch to the default. This branch is ``feature/cmake``. If you missed the ``--branch`` option when cloning then you can switch branches on the command line::
-
-         cd esp-idf
-         git checkout feature/cmake
 
 .. _get-started-setup-path:
 
-Setup Environment Variables
-===========================
+Setup Path to ESP-IDF
+=====================
 
-ESP-IDF requires two environment variables to be set for normal operation:
+The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
 
-- ``IDF_PATH`` should be set to the path to the ESP-IDF root directory.
-- ``PATH`` should include the path to the ``tools`` directory inside the same ``IDF_PATH`` directory.
-
-These two variables should be set up on your PC, otherwise projects will not build.
-
-Setting may be done manually, each time PC is restarted. Another option is to set them permanently in user profile. To do this, follow instructions specific to :ref:`Windows <add-paths-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in section :doc:`add-idf_path-to-profile`.
 
 .. _get-started-start-project:
 
@@ -164,27 +144,16 @@ Start a Project
 
 Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
 
-.. highlight:: bash
-
 Copy :example:`get-started/hello_world` to ``~/esp`` directory::
 
     cd ~/esp
     cp -r $IDF_PATH/examples/get-started/hello_world .
 
-.. highlight:: batch
-
-For **Windows Command Prompt** users, the equivalent commands are::
-
-    cd %userprofile%\esp
-    xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
-
 You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
 
-It is also possible to build examples in-place, without copying them first.
-
 .. important::
 
-    The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
+    The esp-idf build system does not support spaces in paths to esp-idf or to projects.
 
 
 .. _get-started-connect:
@@ -194,32 +163,18 @@ Connect
 
 You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
 
+
 .. _get-started-configure:
 
 Configure
 =========
 
-.. highlight:: bash
-
 Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
 
     cd ~/esp/hello_world
-    idf.py menuconfig
+    make menuconfig
 
-.. highlight:: batch
-
-For **Windows Command Prompt** users::
-
-    cd %userprofile%\esp\hello_world
-    idf.py menuconfig
-
-.. note:: If you get an error about ``idf.py`` not being found, check the ``tools`` directory is part of your Path as described above in :ref:`get-started-setup-path`. If there is no ``idf.py`` in the ``tools`` directory, check you have the correct branch for the CMake preview as shown under :ref:`get-started-get-esp-idf`.
-
-.. note:: Windows users, the Python 2.7 installer will try to configure Windows to associate files with a ``.py`` extension with Python 2. If a separate installed program (such as Visual Studio Python Tools) has created an association with a different version of Python, then running ``idf.py`` may not work. You can either run ``C:\Python27\python idf.py`` each time instead, or change the association that Windows uses for ``.py`` files.
-
-.. note:: Linux users, if your default version of Python is 3.x then you may need to run ``python2 idf.py`` instead.
-
-If previous steps have been done correctly, the following menu will be displayed:
+If previous steps have been done correctly, the following menu will be displayed: 
 
 .. figure:: ../../_static/project-configuration.png
     :align: center
@@ -228,10 +183,17 @@ If previous steps have been done correctly, the following menu will be displayed
 
     Project configuration - Home window
 
+In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
+
+.. note::
+
+   On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
+   (See :doc:`establish-serial-connection` for full details.)
+
 Here are couple of tips on navigation and use of ``menuconfig``:
 
 * Use up & down arrow keys to navigate the menu.
-* Use Enter key to go into a submenu, Escape key to go up a level or exit.
+* Use Enter key to go into a submenu, Escape key to go out or to exit.
 * Type ``?`` to see a help screen. Enter key exits the help screen.
 * Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
 * Pressing ``?`` while highlighting a configuration item displays help about that item.
@@ -241,91 +203,51 @@ Here are couple of tips on navigation and use of ``menuconfig``:
 
     If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
 
+
 .. _get-started-build-flash:
 
-Build The Project and Flash
-===========================
+Build and Flash
+===============
 
-.. highlight:: bash
+Now you can build and flash the application. Run::
 
-Now you can build the project. Run::
+    make flash
 
-    idf.py build
-
-This command will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries.
-
-.. highlight: none
-
-::
-   $ idf.py build
-   Running cmake in directory /path/to/hello_world/build
-   Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
-   Warn about uninitialized values.
-   -- Found Git: /usr/bin/git (found version "2.17.0")
-   -- Building empty aws_iot component due to configuration
-   -- Component names: ...
-   -- Component paths: ...
-   
-   ... (more lines of build system output)
-   
-   [527/527] Generating hello-world.bin
-   esptool.py v2.3.1
-   
-   Project build complete. To flash, run this command:
-   ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin  build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
-   or run 'idf.py flash'
-
-If there are no errors, the build will finish by generating the firmware binary .bin file.
-
-Flash To A Device
-=================
-
-Now you can flash the application to the ESP32 board. Run::
-
-    idf.py -p PORT flash
-
-Replace PORT with the name of your ESP32 board's serial port. On Windows, serial ports have names like ``COM1``. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``. (See :doc:`establish-serial-connection` for full details.)
-
-This step will flash the binaries that you just built to your ESP32 board.
-
-.. note:: Running ``idf.py build`` before ``idf.py flash`` is not actually necessary, the flash step will automatically build the project if required before flashing.
+This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
 
 .. highlight:: none
 
 ::
 
-   Running esptool.py in directory [...]/esp/hello_world
-   Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
-   esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
-   esptool.py v2.3.1
-   Connecting....
-   Detecting chip type... ESP32
-   Chip is ESP32D0WDQ6 (revision 1)
-   Features: WiFi, BT, Dual Core
-   Uploading stub...
-   Running stub...
-   Stub running...
-   Changing baud rate to 460800
-   Changed.
-   Configuring flash size...
-   Auto-detected Flash size: 4MB
-   Flash params set to 0x0220
-   Compressed 22992 bytes to 13019...
-   Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
-   Hash of data verified.
-   Compressed 3072 bytes to 82...
-   Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
-   Hash of data verified.
-   Compressed 136672 bytes to 67544...
-   Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
-   Hash of data verified.
+    esptool.py v2.0-beta2
+    Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
+    esptool.py v2.0-beta2
+    Connecting........___
+    Uploading stub...
+    Running stub...
+    Stub running...
+    Changing baud rate to 921600
+    Changed.
+    Attaching SPI flash...
+    Configuring flash size...
+    Auto-detected Flash size: 4MB
+    Flash params set to 0x0220
+    Compressed 11616 bytes to 6695...
+    Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
+    Hash of data verified.
+    Compressed 408096 bytes to 171625...
+    Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
+    Hash of data verified.
+    Compressed 3072 bytes to 82...
+    Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
+    Hash of data verified.
 
-   Leaving...
-   Hard resetting via RTS pin...
+    Leaving...
+    Hard resetting...
 
-If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.
+If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
 
-.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
+If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
 
 
 .. _get-started-build-monitor:
@@ -333,11 +255,10 @@ If there are no issues, at the end of build process, you should see messages des
 Monitor
 =======
 
-To see if "hello_world" application is indeed running, type ``idf.py -p PORT monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
+To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor <idf-monitor>` application::
 
-    $ idf.py -p /dev/ttyUSB0 monitor
-    Running idf_monitor in directory [...]/esp/hello_world/build
-    Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
+    $ make monitor
+    MONITOR
     --- idf_monitor on /dev/ttyUSB0 115200 ---
     --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
     ets Jun  8 2016 00:22:57
@@ -356,7 +277,7 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo
     Restarting in 8 seconds...
     Restarting in 7 seconds...
 
-To exit the monitor use shortcut ``Ctrl+]``.
+To exit the monitor use shortcut ``Ctrl+]``. 
 
 .. note::
 
@@ -365,19 +286,11 @@ To exit the monitor use shortcut ``Ctrl+]``.
         e���)(Xn@�y.!��(�PW+)��Hn9a؅/9�!�t5��P�~�k��e�ea�5�jA
         ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
 
-    or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+    or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
 
-.. note::
+To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using this application.
 
-   You can combine building, flashing and monitoring into one step as follows::
-
-       idf.py -p PORT flash monitor
-
-Check the section :doc:`IDF Monitor <idf-monitor>` for handy shortcuts and more details on using the monitor.
-
-Check the section :ref:`idf.py` for a full reference of ``idf.py`` commands and options.
-
-That's all what you need to get started with ESP32!
+That's all what you need to get started with ESP32! 
 
 Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
 
@@ -387,27 +300,15 @@ Updating ESP-IDF
 
 After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
 
-.. highlight:: bash
-
 Another solution is to update only what has changed. This method is useful if you have a slow connection to GitHub. To do the update run the following commands::
 
     cd ~/esp/esp-idf
     git pull
     git submodule update --init --recursive
 
-.. highlight:: batch
-
-For **Windows Command Prompt** users::
-
-    cd %userprofile%\esp\esp-idf
-    git pull
-    git submodule update --init --recursive
-
 The ``git pull`` command is fetching and merging changes from ESP-IDF repository on GitHub. Then ``git submodule update --init --recursive`` is updating existing submodules or getting a fresh copy of new ones. On GitHub the submodules are represented as links to other repositories and require this additional command to get them onto your PC.
 
-.. highlight:: bash
-
-To use a specific release of ESP-IDF, e.g. `v2.1`, run::
+If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
 
     cd ~/esp
     git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
@@ -415,22 +316,8 @@ To use a specific release of ESP-IDF, e.g. `v2.1`, run::
     git checkout v2.1
     git submodule update --init --recursive
 
-.. highlight:: batch
-
-For **Windows Command Prompt** users::
-
-    cd %userprofile%\esp
-    git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
-    cd esp-idf-v2.1/
-    git checkout v2.1
-    git submodule update --init --recursive
-
 After that remember to :doc:`add-idf_path-to-profile`, so the toolchain scripts know where to find the ESP-IDF in it's release specific location.
 
-.. note::
-
-   Different versions of ESP-IDF may have different setup or prerequisite requirements, or require different toolchain versions. If you experience any problems, carefully check the Getting Started documentation for the version you are switching to.
-
 
 Related Documents
 =================
diff --git a/docs/en/get-started/linux-setup-scratch.rst b/docs/en/get-started/linux-setup-scratch.rst
index 1c1d287e8..b2cb96ec3 100644
--- a/docs/en/get-started/linux-setup-scratch.rst
+++ b/docs/en/get-started/linux-setup-scratch.rst
@@ -2,9 +2,6 @@
 Setup Linux Toolchain from Scratch
 **********************************
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
 The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
 
 
@@ -13,20 +10,14 @@ Install Prerequisites
 
 To compile with ESP-IDF you need to get the following packages:
 
-- CentOS 7::
-
-    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
-
 - Ubuntu and Debian::
 
-    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
+    sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
 
-.. note::
-    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
 
 Compile the Toolchain from Source
 =================================
@@ -35,19 +26,19 @@ Compile the Toolchain from Source
 
   - CentOS 7::
 
-        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
+        sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
 
   - Ubuntu pre-16.04::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
 
   - Ubuntu 16.04::
 
-        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
 
   - Debian 9::
 
-        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
+        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
 
   - Arch::
 
diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst
index 1b884be7f..bdc4467ce 100644
--- a/docs/en/get-started/linux-setup.rst
+++ b/docs/en/get-started/linux-setup.rst
@@ -3,9 +3,6 @@ Standard Setup of Toolchain for Linux
 *************************************
 :link_to_translation:`zh_CN:[中文]`
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
 Install Prerequisites
 =====================
 
@@ -13,18 +10,16 @@ To compile with ESP-IDF you need to get the following packages:
 
 - CentOS 7::
 
-    sudo yum install git wget ncurses-devel flex bison gperf python pyserial cmake ninja-build ccache
+    sudo yum install gcc git wget make ncurses-devel flex bison gperf python pyserial
 
 - Ubuntu and Debian::
 
-    sudo apt-get install git wget libncurses-dev flex bison gperf python python-serial cmake ninja-build ccache
+    sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-serial
 
 - Arch::
 
-    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial cmake ninja ccache
+    sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
 
-.. note::
-    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, or enabling of a "backports" repository, or installing of a "cmake3" package not "cmake")
 
 Toolchain Setup
 ===============
@@ -84,7 +79,7 @@ With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0
 Arch Linux Users
 ----------------
 
-To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
+To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6. 
 
 Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
 
diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst
index 53b8a9947..7516158a1 100644
--- a/docs/en/get-started/macos-setup-scratch.rst
+++ b/docs/en/get-started/macos-setup-scratch.rst
@@ -2,16 +2,6 @@
 Setup Toolchain for Mac OS from Scratch
 ***************************************
 
-Package Manager
-===============
-
-To set up the toolchain from scratch, rather than `downloading a precocmpiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or homebrew_ package manager.
-
-MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
-
-    .. _homebrew: https://brew.sh/
-    .. _MacPorts: https://www.macports.org/install.php
-
 Install Prerequisites
 =====================
 
@@ -23,28 +13,24 @@ Install Prerequisites
 
     sudo pip install pyserial
 
-- install CMake & Ninja build:
-
-  - If you have HomeBrew, you can run::
-
-      brew install cmake ninja
-
-  - If you have MacPorts, you can run::
-
-      sudo port install cmake ninja
 
 Compile the Toolchain from Source
 =================================
 
 - Install dependencies:
 
+  - Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
+    
+    .. _homebrew: https://brew.sh/
+    .. _MacPorts: https://www.macports.org/install.php
+
   - with MacPorts::
 
-        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
+        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
 
   - with homebrew::
 
-        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
+        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
 
 Create a case-sensitive filesystem image::
 
diff --git a/docs/en/get-started/macos-setup.rst b/docs/en/get-started/macos-setup.rst
index 9c42d4759..16123cb03 100644
--- a/docs/en/get-started/macos-setup.rst
+++ b/docs/en/get-started/macos-setup.rst
@@ -3,14 +3,9 @@ Standard Setup of Toolchain for Mac OS
 **************************************
 :link_to_translation:`zh_CN:[中文]`
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
 Install Prerequisites
 =====================
 
-ESP-IDF will use the version of Python installed by default on Mac OS.
-
 - install pip::
 
     sudo easy_install pip
@@ -19,26 +14,6 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
 
     sudo pip install pyserial
 
-- install CMake & Ninja build:
-
-  - If you have HomeBrew_, you can run::
-
-      brew install cmake ninja
-
-  - If you have MacPorts_, you can run::
-
-      sudo port install cmake ninja
-
-  - Otherwise, consult the CMake_ and Ninja_ home pages for Mac OS installation downloads.
-
-- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
-
-.. note::
-   If an error like this is shown during any step::
-
-     xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
-
-    Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
 
 Toolchain Setup
 ===============
@@ -73,6 +48,7 @@ Next Steps
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
+
 Related Documents
 =================
 
@@ -80,9 +56,3 @@ Related Documents
     :maxdepth: 1
 
     macos-setup-scratch
-
-.. _cmake: https://cmake.org/
-.. _ninja: https://ninja-build.org/
-.. _ccache: https://ccache.samba.org/
-.. _homebrew: https://brew.sh/
-.. _MacPorts: https://www.macports.org/install.php
diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst
index f7ee77081..4c772eeb3 100644
--- a/docs/en/get-started/windows-setup-scratch.rst
+++ b/docs/en/get-started/windows-setup-scratch.rst
@@ -2,81 +2,91 @@
 Setup Windows Toolchain from Scratch
 ************************************
 
-This is a step-by-step alternative to running the :doc:`ESP-IDF Tools Installer <windows-setup>` for the CMake-based build system. Installing all of the tools by hand allows more control over the process, and also provides the information for advanced users to customize the install.
+Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps. 
 
-To quickly setup the toolchain and other tools in standard way, using the ESP-IDF Tools installer, proceed to section :doc:`windows-setup`.
-
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
-.. note::
-
-    Unlike the previous "GNU Make" based ESP-IDF build environment, the cmake environment does not include or require MSYS2 or any other Unix compatibility layer.
-
-Tools
-=====
-
-cmake
-^^^^^
-
-Download the latest stable release of CMake_ for Windows and run the installer.
-
-When the installer asks for Install Options, choose either "Add CMake to the system PATH for all users" or "Add CMake to the system PATH for the current user".
-
-Ninja build
-^^^^^^^^^^^
-
-.. note::
-    Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented.
-
-Download the ninja_ latest stable Windows release from the (`download page <ninja-dl>`_).
-
-The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_ (or you can choose a directory which is already on your Path).
+To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
 
 
-Python 2.x
-^^^^^^^^^^
+.. _configure-windows-toolchain-from-scratch:
 
-Download the latest Python_ 2.7 for Windows installer, and run it.
+Configure Toolchain & Environment from Scratch
+==============================================
 
-The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".
+This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
 
-Once Python is installed, open a Windows Command Prompt from the Start menu and run the following command::
+* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
 
-  pip install pyserial
+* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
 
-MConf for IDF
-^^^^^^^^^^^^^
+* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
 
-Download the configuration tool mconf-idf from the `kconfig-frontends releases page <mconf-idf>`_. This is the ``mconf`` configuration tool with some minor customizations for ESP-IDF.
+  *(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
 
-This tool will also need to be unzipped to a directory which is then `added to your Path <add-directory-windows-path>`_.
+* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
 
-Toolchain Setup
-===============
+* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
 
-Download the precompiled Windows toolchain from dl.espressif.com:
+* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
+
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
+
+     *** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
+
+  If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
+
+* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
+
+
+MSYS2 Mirrors in China
+~~~~~~~~~~~~~~~~~~~~~~
+
+There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
+
+To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
+
+Add these lines at the top of ``mirrorlist.mingw32``::
+
+  Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
+  Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
+
+Add these lines at the top of ``mirrorlist.msys``::
+
+  Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
+  Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
+
+
+HTTP Proxy
+~~~~~~~~~~
+
+You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
+
+    export http_proxy='http://http.proxy.server:PORT'
+
+Or with credentials::
+
+    export http_proxy='http://user:password@http.proxy.server:PORT'
+
+Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
+
+
+Alternative Setup: Just download a toolchain
+============================================
+
+If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
 
 https://dl.espressif.com/dl/xtensa-esp32-elf-win32-1.22.0-80-g6c4433a-5.2.0.zip
 
-Unzip the zip file to ``C:\Program Files`` (or some other location). The zip file contains a single directory ``xtensa-esp32-elf``.
-
-Next, the ``bin`` subdirectory of this directory must be `added to your Path <add-directory-windows-path>`_. For example, the directory to add may be ``C:\Program Files\xtensa-esp32-elf\bin``.
-
 .. note::
-   If you already have the MSYS2 environment (for use with the "GNU Make" build system) installed, you can skip the separate download and add the directory ``C:\msys32\opt\xtensa-esp32-elf\bin`` to the Path instead, as the toolchain is included in the MSYS2 environment.
 
+	If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
 
-.. _add-directory-windows-path:
+.. important::
 
-Adding Directory to Path
-========================
-
-To add any new directory to your Windows Path environment variable:
-
-Open the System control panel and navigate to the Environment Variables dialog. (On Windows 10, this is found under Advanced System Settings).
-
-Double-click the ``Path`` variable (either User or System Path, depending if you want other users to have this directory on their path.) Go to the end of the value, and append ``;<new value>``.
+	Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
 
 
 Next Steps
@@ -84,5 +94,22 @@ Next Steps
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
-.. _ninja: https://ninja-build.org/
-.. _Python: https://www.python.org/downloads/windows/
+.. _updating-existing-windows-environment:
+
+Updating The Environment
+========================
+
+When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
+
+Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
+
+- Update IDF to the new version you want to use.
+- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
+
+The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
+
+If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
+
+.. _MSYS2: https://msys2.github.io/
+.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
+.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new
diff --git a/docs/en/get-started/windows-setup.rst b/docs/en/get-started/windows-setup.rst
index c84959a96..9b143920b 100644
--- a/docs/en/get-started/windows-setup.rst
+++ b/docs/en/get-started/windows-setup.rst
@@ -3,61 +3,64 @@ Standard Setup of Toolchain for Windows
 ***************************************
 :link_to_translation:`zh_CN:[中文]`
 
-.. note::
-   This is documentation for the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
-.. note::
-      The CMake-based build system is only supported on 64-bit versions of Windows.
-
 Introduction
 ============
 
-ESP-IDF requires some prerequisite tools to be installed so you can build firmware for the ESP32. The prerequisite tools include Git, a cross-compiler and the CMake build tool. We'll go over each one in this document.
+Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
 
-For this Getting Started we're going to use a command prompt, but after ESP-IDF is installed you can use :doc:`Eclipse <eclipse-setup>` or another graphical IDE with CMake support instead.
 
-.. note::
-   Previous versions of ESP-IDF used a GNU Make based build system, which required the MSYS2_ Unix compatibility environment on Windows. This is no longer required.
+Toolchain Setup 
+===============
 
-ESP-IDF Tools Installer
-=======================
+The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
 
-The easiest way to install ESP-IDF's prerequisites is to download the ESP-IDF Tools installer from this URL:
+https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip
 
-https://dl.espressif.com/dl/esp-idf-tools-setup-1.1.exe
+Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
 
-The installer will automatically install the ESP32 Xtensa gcc toolchain, Ninja_ build tool, and a configuration tool called mconf-idf_. The installer can also download and run installers for CMake_ and Python_ 2.7 if these are not already installed on the computer.
 
-By default, the installer updates the Windows ``Path`` environment variable so all of these tools can be run from anywhere. If you disable this option, you will need to configure the environment where you are using ESP-IDF (terminal or chosen IDE) with the correct paths.
+Check it Out
+============
 
-Note that this installer is for the ESP-IDF Tools package, it doesn't include ESP-IDF itself.
+Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
 
-Installing Git
-==============
+    mkdir -p ~/esp
 
-The ESP-IDF tools installer does not install Git. By default, the getting started guide assumes you will be using Git on the command line. You can download and install a command line Git for Windows (along with the "Git Bash" terminal) from `Git For Windows`_.
+By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step.
 
-If you prefer to use a different graphical Git client, then you can install one such as `Github Desktop`. You will need to translate the Git commands in the Getting Started guide for use with your chosen Git client.
+.. figure:: ../../_static/msys2-terminal-window.png
+    :align: center
+    :alt: MSYS2 MINGW32 shell window
+    :figclass: align-center
 
-Using a Terminal
-================
+    MSYS2 MINGW32 shell window
 
-For the remaining Getting Started steps, we're going to use a terminal command prompt. It doesn't matter which command prompt you use:
+Use this window in the following steps setting up development environment for ESP32.
 
-- You can use the built-in Windows Command Prompt, under the Start menu. Note that command line instructions in this documentation give "bash" commands for Mac OS or Linux first. The Windows Command Prompt equivalent is given afterwards.
-- You can use the "Git Bash" terminal which is part of `Git for Windows`_. This uses the same "bash" command prompt syntax as Mac OS or Linux. You can find it in the Start menu once installed.
-- If you have MSYS2_ installed (maybe from a previous ESP-IDF version), then you can also use the MSYS terminal.
 
 Next Steps
 ==========
 
 To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
 
+Updating The Environment
+========================
+
+When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
+
+- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
+- Download the new precompiled environment using the steps above.
+- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
+- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
+- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
+
+You can have independent different MSYS2 environments on your system, as long as they are in different directories.
+
+There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
+
 Related Documents
 =================
 
-For advanced users who want to customize the install process:
-
 .. toctree::
     :maxdepth: 1
 
@@ -65,9 +68,3 @@ For advanced users who want to customize the install process:
 
 
 .. _MSYS2: https://msys2.github.io/
-.. _cmake: https://cmake.org/download/
-.. _ninja: https://ninja-build.org/
-.. _Python: https://www.python.org/downloads/windows/
-.. _Git for Windows: https://gitforwindows.org/
-.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
-.. _Github Desktop: https://desktop.github.com/
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 907d8f734..80cdfd482 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -4,9 +4,6 @@ ESP-IDF Programming Guide
 
 This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
 
-.. note::
-   This is documentation for the the CMake-based build system which is currently in preview release. The documentation may have gaps, and you may encounter bugs (please report either of these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
-
 The documentation has different language versions (:link_to_translation:`en:English`, :link_to_translation:`zh_CN:中文版`, :doc:`How to switch between languages? <languages>`). However, please refer to the English version if there is any discrepancy.
 
 ==================  ==================  ==================
@@ -43,6 +40,7 @@ The documentation has different language versions (:link_to_translation:`en:Engl
    :hidden:
 
    Get Started <get-started/index>
+   Get Started (CMake Preview) <get-started-cmake/index>
    API Reference <api-reference/index>
    H/W Reference <hw-reference/index>
    API Guides <api-guides/index>
diff --git a/docs/zh_CN/api-guides/build-system-cmake.rst b/docs/zh_CN/api-guides/build-system-cmake.rst
new file mode 100644
index 000000000..d70290e6e
--- /dev/null
+++ b/docs/zh_CN/api-guides/build-system-cmake.rst
@@ -0,0 +1 @@
+.. include:: ../../en/api-guides/build-system-cmake.rst
diff --git a/docs/zh_CN/api-guides/gnu-make-build-system.rst b/docs/zh_CN/api-guides/gnu-make-build-system.rst
deleted file mode 100644
index 19bc45fc3..000000000
--- a/docs/zh_CN/api-guides/gnu-make-build-system.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../en/api-guides/gnu-make-build-system.rst
diff --git a/docs/zh_CN/cmake-pending-features.rst b/docs/zh_CN/cmake-pending-features.rst
new file mode 100644
index 000000000..6a45fbef9
--- /dev/null
+++ b/docs/zh_CN/cmake-pending-features.rst
@@ -0,0 +1 @@
+.. include:: /../en/cmake-pending-features.rst
diff --git a/docs/zh_CN/cmake-warning.rst b/docs/zh_CN/cmake-warning.rst
new file mode 100644
index 000000000..09479207f
--- /dev/null
+++ b/docs/zh_CN/cmake-warning.rst
@@ -0,0 +1 @@
+.. include:: /../en/cmake-warning.rst
diff --git a/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst b/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst
new file mode 100644
index 000000000..2aacd4a4e
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/add-idf_path-to-profile.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/add-idf_path-to-profile.rst
diff --git a/docs/zh_CN/get-started-cmake/eclipse-setup.rst b/docs/zh_CN/get-started-cmake/eclipse-setup.rst
new file mode 100644
index 000000000..b7fd85471
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/eclipse-setup.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/eclipse-setup.rst
diff --git a/docs/zh_CN/get-started-cmake/establish-serial-connection.rst b/docs/zh_CN/get-started-cmake/establish-serial-connection.rst
new file mode 100644
index 000000000..29f14b710
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/establish-serial-connection.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/establish-serial-connection.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst b/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst
new file mode 100644
index 000000000..155d0a53c
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-devkitc-v2.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-devkitc-v2.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-devkitc.rst b/docs/zh_CN/get-started-cmake/get-started-devkitc.rst
new file mode 100644
index 000000000..922a1445b
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-devkitc.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-devkitc.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-pico-kit-v3.rst b/docs/zh_CN/get-started-cmake/get-started-pico-kit-v3.rst
new file mode 100644
index 000000000..5cb327a30
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-pico-kit-v3.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-pico-kit-v3.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-pico-kit.rst b/docs/zh_CN/get-started-cmake/get-started-pico-kit.rst
new file mode 100644
index 000000000..d409f1d16
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-pico-kit.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-pico-kit.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-wrover-kit-v2.rst b/docs/zh_CN/get-started-cmake/get-started-wrover-kit-v2.rst
new file mode 100644
index 000000000..a742059bd
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-wrover-kit-v2.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-wrover-kit-v2.rst
diff --git a/docs/zh_CN/get-started-cmake/get-started-wrover-kit.rst b/docs/zh_CN/get-started-cmake/get-started-wrover-kit.rst
new file mode 100644
index 000000000..23227d7d5
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/get-started-wrover-kit.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/get-started-wrover-kit.rst
diff --git a/docs/zh_CN/get-started-cmake/idf-monitor.rst b/docs/zh_CN/get-started-cmake/idf-monitor.rst
new file mode 100644
index 000000000..05b457188
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/idf-monitor.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/idf-monitor.rst
diff --git a/docs/zh_CN/get-started-cmake/index.rst b/docs/zh_CN/get-started-cmake/index.rst
new file mode 100644
index 000000000..5c49b60a4
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/index.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/index.rst
diff --git a/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst b/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst
new file mode 100644
index 000000000..1bc3dfab7
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/linux-setup-scratch.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/linux-setup-scratch.rst
diff --git a/docs/zh_CN/get-started-cmake/linux-setup.rst b/docs/zh_CN/get-started-cmake/linux-setup.rst
new file mode 100644
index 000000000..048417a90
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/linux-setup.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/linux-setup.rst
diff --git a/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst b/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst
new file mode 100644
index 000000000..82b866534
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/macos-setup-scratch.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/macos-setup-scratch.rst
diff --git a/docs/zh_CN/get-started-cmake/macos-setup.rst b/docs/zh_CN/get-started-cmake/macos-setup.rst
new file mode 100644
index 000000000..e1bf5a2f6
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/macos-setup.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/macos-setup.rst
diff --git a/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst b/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst
new file mode 100644
index 000000000..2bad626c9
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/toolchain-setup-scratch.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/toolchain-setup-scratch.rst
diff --git a/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst b/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst
new file mode 100644
index 000000000..6ec60d320
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/windows-setup-scratch.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/windows-setup-scratch.rst
diff --git a/docs/zh_CN/get-started-cmake/windows-setup.rst b/docs/zh_CN/get-started-cmake/windows-setup.rst
new file mode 100644
index 000000000..b03ce8af0
--- /dev/null
+++ b/docs/zh_CN/get-started-cmake/windows-setup.rst
@@ -0,0 +1 @@
+.. include:: ../../en/get-started-cmake/windows-setup.rst
diff --git a/docs/zh_CN/get-started/eclipse-setup-windows.rst b/docs/zh_CN/get-started/eclipse-setup-windows.rst
new file mode 100644
index 000000000..dbd07b565
--- /dev/null
+++ b/docs/zh_CN/get-started/eclipse-setup-windows.rst
@@ -0,0 +1,82 @@
+*****************************************************
+Eclipse IDE 的创建和烧录指南（Windows 平台）
+*****************************************************
+:link_to_translation:`en:[English]`
+
+Windows 平台上的 Eclipse 配置略有不同，具体步骤请见下文。
+
+注意：OS X 和 Linux 平台上的 Eclipse IDE 配置，请见 :doc:`Eclipse IDE page <eclipse-setup>`。
+
+安装 Eclipse IDE
+==================
+
+Windows 平台的 Eclipse 安装步骤与其他平台相同，请见 :ref:`Installing Eclipse IDE <eclipse-install-steps>`。
+
+.. _eclipse-windows-setup:
+
+
+Windows 平台上的 Eclipse 配置
+================================
+
+完成 Eclipse IDE 的安装后，请按照下列步骤继续操作：
+
+导入新项目
+-------------
+
+* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
+
+* 运行 Eclipse，选择 “File” -> “Import...”。
+
+* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
+
+* 下个界面，在 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应填入 ESP-IDF 项目的路径，而非 ESP-IDF 的路径（稍后再填写）。此外，您指定的目录中应包含名为 “Makefile”（项目 Makefile）的文件。
+
+* 在同一页面上，在 “Toolchain for Indexer Settings” 下取消选中 “Show only available toolchains that support this platform”。
+
+* 在出现的扩展列表中，选择 “Cygwin GCC”。然后点击 “Finish”。
+
+*注意：您可能看到有关“无法找到 Cygwin GCC 工具链”的警告。这种情况并不影响安装，我们只需重新配置 Eclipse，并找到我们的工具链即可。*
+
+项目属性 
+----------
+
+* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择顶层 “Properties”。
+
+* 点击 “C/C++ Build” 属性页。
+
+	* 取消选中 “Use default build command”，然后输入命令：``python${IDF_PATH}/tools/windows/eclipse_make.py``，开始自定义创建。
+
+* 点击 “C/C++ Build” 下的 “Environment” 属性页面。
+
+	* 选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
+
+	* 再次点击 “Add...”，输入名称 ``IDF_PATH``，并填写 ESP-IDF 的完整安装路径。``IDF_PATH`` 目录路径应使用正斜杠，而非反斜线，即 ``C:/Users/user-name/Development/esp-idf``。
+
+	* 选择 PATH 环境变量，删除默认值，并将其替换为 ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` （如果您已经将 msys32 安装到其他目​​录，这里请自行调整）。
+
+
+* 点击 “C/C++ General” -> “Preprocessor Include Paths, Macros, etc.” 属性页。
+
+	* 点击 “Providers” 选项卡。
+
+		* 从 “Providers” 列表中选择 “CDT GCC Built-in Compiler Settings Cygwin”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终完整的 ``Command to get compiler specs`` 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
+		
+		* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``，并用括号把剩余部分扩起来。最终的完整 Compiler 命令模式应为 ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``。
+
+
+在 Eclipse IDE 中创建项目
+---------------------------
+
+Windows 平台的 Eclipse 项目创建步骤与其他平台相同，请见 :ref:`Building in Eclipse <eclipse-build-project>`。
+
+技术细节
+=========
+
+**以下内容仅供 Windows 平台专家或非常感兴趣的开发者阅读。**
+
+Windows 平台的 Eclipse 介绍到此结束，下方将主要将介绍一些关键步骤的原理，助您了解更多 Eclipse 的背景信息。
+
+* 首先，xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链，但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于：msys2 需要使用 Cygwin，并支持 Unix 风格的路径，即 ``/c/blah``，而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是，``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能，其内置 “include” 目录全部位于 ``/usr/`` 路径下，这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 风格路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器，可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。
+
+
+* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果，查找头文件目录，但是无法脱离 ``cygpath``，直接解析类似 ``/c/blah`` 的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 ``cygpath``，但由于未知原因，目前 ESP-IDF 配置并不会触发该功能。出于这个原因，我们会使用 ``eclipse_make.py`` 包装脚本调用 ``make``，然后使用 ``cygpath`` 处理 Eclipse 的结果。
diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst
index e1bebd50e..e2f7be8a3 100644
--- a/docs/zh_CN/get-started/eclipse-setup.rst
+++ b/docs/zh_CN/get-started/eclipse-setup.rst
@@ -3,6 +3,107 @@ Eclipse IDE 的创建和烧录指南
 ****************************
 :link_to_translation:`en:[English]`
 
-.. important:: 对不起，CMake-based Build System Preview 还没有中文翻译。
+.. _eclipse-install-steps:
+
+安装 Eclipse IDE
+================
+
+Eclipse IDE 是一个可视化的集成开发环境，可用于编写、编译和调试 ESP-IDF 项目。
+
+* 首先，请在您的平台上安装相应的 ESP-IDF，具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。
+
+* 我们建议，您应首先使用命令行创建一个项目，大致熟悉项目的创建流程。此外，您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前，Eclipse 尚不支持对 ESP-IDF 项目进行配置。
+
+* 下载相应版本的 Eclipse Installer 至您的平台，点击 eclipse.org_。
+
+* 运行 Eclipse Installer，选择 “Eclipse for C/C++ Development”（有的版本也可能显示为 CDT）。
+
+Windows 用户
+============
+
+在 Windows 平台上使用 Eclipse IDE 的用户，请参考 :ref:`Windows 用户的 Eclipse IDE 使用指南 <eclipse-windows-setup>`。
+
+配置 Eclipse IDE
+=================
+
+请打开安装好的 Eclipse IDE，并按照以下步骤进行操作：
+
+导入新项目
+----------
+
+* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此，在使用 Eclipse 前，您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时，您可以使用 GitHub 中的 idf-template 项目模版，或从 esp-idf 子目录中选择一个 example。
+
+* 运行 Eclipse，选择 “File” -> “Import...”。
+
+* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”，然后点击 “Next”。
+
+* 在下个界面中 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意，这里应输入 ESP-IDF 项目的路径，而非 ESP-IDF 本身的路径（这个稍后再填）。此外，您指定的目标路径中应包含名为 ``Makefile`` （项目 Makefile）的文件。
+
+* 在本界面，找到 “Toolchain for Indexer Settings”，选择 “Cross GCC”，最后点击 “Finish”。
+
+
+项目属性
+--------
+
+* 新项目将出现在 “Project Explorer” 下。请右键选择该项目，并在菜单中选择 “Properties”。
+
+* 点击 “C/C++ Build” 下的 “Environment” 属性页，选择 “Add...”，并在对应位置输入 ``BATCH_BUILD`` 和 ``1``。
+
+* 再次点击 “Add...”，并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。
+
+* 选择 “PATH” 环境变量，不要改变默认值。如果 Xtensa 工具链的路径尚不在 “PATH” 列表中，则应将该路径 (``something/xtensa-esp32-elf/bin``) 增加至列表。
+
+* 在 macOS 平台上，增加一个 “PYTHONPATH” 环境变量，并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``， 保证系统中预先安装的 Python （需安装 pyserial 模块）可以覆盖 Eclipse 内置的任何 Python。
+
+* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。
+
+	* 点击 “Providers” 选项卡。从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”。在 “Command to get compiler specs” 输入框中，用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``${COMMAND}``，最终的完整 “Command to get compiler specs” 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``。
+
+	* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”，然后在 “Compiler command pattern“ 输入框的起始位置输入 ``xtensa-esp32-elf-``，最终的完整编译器命令应为 ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``。
+
+.. _eclipse-build-project:
+
+在 Eclipse IDE 中创建项目
+--------------------------
+
+在首次创建项目前，Eclipse IDE 可能会显示大量有关未定义值的错误和警告，主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目创建过程中自动生成的。因此，这些错误和警告将在 ESP-IDF 项目生成完成后消失。
+
+* 点击 “OK”，关闭 Eclipse IDE 中的 “Properties” 对话框。
+
+* 在 Eclipse IDE 界面外，打开命令管理器。进入项目目录，并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段，您还无法在 Eclipse 中完成本操作。
+
+*如果您未进行最开始的配置步骤，ESP-IDF 将提示在命令行中进行配置 - 但由于 Eclipse 暂时不支持相关功能，因此该项目将挂起或创建失败。*
+
+* 返回 Eclipse IDE 界面中，选择 “Project” -> “Build” 创建您的项目。
+
+**提示**：如果您已经在 Eclipse IDE 环境外创建了项目，则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”，允许 Eclipse 查看所有源文件的编译器参数，并借此确定头文件包含路径。
+
+在 Eclipse IDE 中烧录项目
+--------------------------
+
+您可以将 ``make flash`` 目标放在 Eclipse 项目中，通过 Eclipse UI 调用 ``esptool.py`` 进行烧录：
+
+* 打开 “Project Explorer”，并右击您的项目（请注意右击项目本身，而非项目下的子文件，否则 Eclipse 可能会找到错误的 ``Makefile``）。
+
+* 从菜单中选择 “Make Targets” -> “Create”。
+
+* 输入 “flash” 为目标名称，其他选项使用默认值。
+
+* 选择 “Project” -> “Make Target” -> “Build (快捷键：Shift + F9）”，创建自定义烧录目标，用于编译、烧录项目。
+
+注意，您将需要通过 ``make menuconfig``，设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令行操作（请见平台的对应指南）。
+
+如有需要，请按照相同步骤添加 ``bootloader`` 和 ``partition_table``。
+
+相关文档
+--------
+
+.. toctree::
+    :maxdepth: 1
+
+    eclipse-setup-windows
+
+
+.. _eclipse.org: https://www.eclipse.org/
 
 
diff --git a/docs/zh_CN/index.rst b/docs/zh_CN/index.rst
index 9945da9bc..2a961055b 100644
--- a/docs/zh_CN/index.rst
+++ b/docs/zh_CN/index.rst
@@ -40,6 +40,7 @@ ESP-IDF 编程指南
    :hidden:
 
    快速入门 <get-started/index>
+   快速入门 (CMake 预览版本) <get-started-cmake/index>
    API 参考 <api-reference/index>
    H/W 参考 <hw-reference/index>
    API 指南 <api-guides/index>
diff --git a/tools/idf.py b/tools/idf.py
index 5837060fb..abf098445 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -346,7 +346,7 @@ def print_closing_message(args):
             args.port or "(PORT)",
             args.baud,
             cmd.strip()))
-        print("or run 'idf.py %s'" % (key + "-flash" if key != "project" else "flash",))
+        print("or run 'idf.py -p PORT %s'" % (key + "-flash" if key != "project" else "flash",))
 
     if "all" in args.actions or "build" in args.actions:
         print_flashing_message("Project", "project")
diff --git a/tools/kconfig_new/confgen.py b/tools/kconfig_new/confgen.py
index b78967d48..416c28d88 100755
--- a/tools/kconfig_new/confgen.py
+++ b/tools/kconfig_new/confgen.py
@@ -33,6 +33,9 @@ import pprint
 
 __version__ = "0.1"
 
+if not "IDF_CMAKE" in os.environ:
+    os.environ["IDF_CMAKE"] = ""
+
 def main():
     parser = argparse.ArgumentParser(description='confgen.py v%s - Config Generation Tool' % __version__, prog=os.path.basename(sys.argv[0]))
 

From 04238fa5e5b9b13abe4a9f808172b1978d26fe75 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 9 Aug 2018 09:48:17 +1000
Subject: [PATCH 092/112] docs: Python 3 Sphinx compatibility

---
 docs/conf_common.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/conf_common.py b/docs/conf_common.py
index ec9196992..be7b86ffd 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -41,11 +41,11 @@ copy_if_modified('xml/', 'xml_in/')
 os.system('python ../gen-dxd.py')
 
 # Generate 'kconfig.inc' file from components' Kconfig files
-print "Generating kconfig.inc from kconfig contents"
+print("Generating kconfig.inc from kconfig contents")
 kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
 temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
-kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"])
-kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"])
+kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"]).decode()
+kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"]).decode()
 confgen_args = ["python",
                 "../../tools/kconfig_new/confgen.py",
                 "--kconfig", "../../Kconfig",

From 70288f864e4e6ebc8dc65eac91279b10a09fcd91 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 10 Aug 2018 12:18:25 +1000
Subject: [PATCH 093/112] cmake: Expand components relative to PROJECT_PATH
 correctly

---
 tools/cmake/project.cmake                     | 4 +++-
 tools/cmake/scripts/expand_requirements.cmake | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index 86174feb8..e346bcbf2 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -59,8 +59,10 @@ macro(project name)
         -D "DEPENDENCIES_FILE=${CMAKE_BINARY_DIR}/component_depends.cmake"
         -D "COMPONENT_DIRS=${COMPONENT_DIRS}"
         -D "BOOTLOADER_BUILD=${BOOTLOADER_BUILD}"
+        -D "IDF_PATH=${IDF_PATH}"
+        -D "DEBUG=${DEBUG}"
         -P "${IDF_PATH}/tools/cmake/scripts/expand_requirements.cmake"
-        WORKING_DIRECTORY "${IDF_PATH}/tools/cmake")
+        WORKING_DIRECTORY "${PROJECT_PATH}")
     include("${CMAKE_BINARY_DIR}/component_depends.cmake")
 
     # We now have the following component-related variables:
diff --git a/tools/cmake/scripts/expand_requirements.cmake b/tools/cmake/scripts/expand_requirements.cmake
index 9b56cf090..d602801bb 100644
--- a/tools/cmake/scripts/expand_requirements.cmake
+++ b/tools/cmake/scripts/expand_requirements.cmake
@@ -15,7 +15,7 @@
 #
 # TODO: Error out if a component requirement is missing
 cmake_minimum_required(VERSION 3.5)
-include("utilities.cmake")
+include("${IDF_PATH}/tools/cmake/utilities.cmake")
 
 if(NOT DEPENDENCIES_FILE)
     message(FATAL_ERROR "DEPENDENCIES_FILE must be set.")
@@ -91,8 +91,10 @@ function(components_find_all component_dirs component_paths component_names)
 
     # Look for a component in each component_dirs entry
     foreach(dir ${component_dirs})
+        debug("Looking for CMakeLists.txt in ${dir}")
         file(GLOB component "${dir}/CMakeLists.txt")
         if(component)
+            debug("CMakeLists.txt file ${component}")
             get_filename_component(component "${component}" DIRECTORY)
             get_filename_component(name "${component}" NAME)
             if(NOT name IN_LIST names)

From 48bd67524dc3dd461f3616ac1d9a6bfe3ee6fb06 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 10 Aug 2018 12:30:32 +1000
Subject: [PATCH 094/112] cmake: Only rewrite componend_depends.cmake if it
 changes

---
 tools/cmake/scripts/expand_requirements.cmake | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/tools/cmake/scripts/expand_requirements.cmake b/tools/cmake/scripts/expand_requirements.cmake
index d602801bb..a825a7647 100644
--- a/tools/cmake/scripts/expand_requirements.cmake
+++ b/tools/cmake/scripts/expand_requirements.cmake
@@ -184,10 +184,10 @@ debug("components in build: ${build_component_paths}")
 debug("components not found: ${not_found}")
 
 function(line contents)
-    file(APPEND "${DEPENDENCIES_FILE}" "${contents}\n")
+    file(APPEND "${DEPENDENCIES_FILE}.tmp" "${contents}\n")
 endfunction()
 
-file(WRITE "${DEPENDENCIES_FILE}" "# Component requirements generated by expand_requirements.cmake\n\n")
+file(WRITE "${DEPENDENCIES_FILE}.tmp" "# Component requirements generated by expand_requirements.cmake\n\n")
 line("set(BUILD_COMPONENTS ${build_components})")
 line("set(BUILD_COMPONENT_PATHS ${build_component_paths})")
 line("")
@@ -216,3 +216,7 @@ endforeach()
 
 line("  message(FATAL_ERROR \"Component not found: \${component}\")")
 line("endfunction()")
+
+# only replace DEPENDENCIES_FILE if it has changed (prevents ninja/make build loops.)
+execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different "${DEPENDENCIES_FILE}.tmp" "${DEPENDENCIES_FILE}")
+execute_process(COMMAND ${CMAKE_COMMAND} -E remove "${DEPENDENCIES_FILE}.tmp")

From 068a3e2f6ad31f7eebf81e821ec352bc557f9446 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 20 Aug 2018 10:47:42 +1000
Subject: [PATCH 095/112] cmake: Fix flasher argument generation

---
 .../partition_table/project_include.cmake     | 25 +++++++++----------
 1 file changed, 12 insertions(+), 13 deletions(-)

diff --git a/components/partition_table/project_include.cmake b/components/partition_table/project_include.cmake
index cb3611d30..b09ffd358 100644
--- a/components/partition_table/project_include.cmake
+++ b/components/partition_table/project_include.cmake
@@ -24,25 +24,24 @@ endif()
 set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${PARTITION_CSV_PATH})
 
 # Parse the partition table to get variable partition offsets & sizes which must be known at CMake runtime
-set(get_part_info ${COMPONENT_PATH}/parttool.py -q)
+function(get_partition_info variable get_part_info_args)
+    separate_arguments(get_part_info_args)
+    execute_process(COMMAND
+        ${COMPONENT_PATH}/parttool.py -q ${get_part_info_args} ${PARTITION_CSV_PATH}
+        OUTPUT_VARIABLE result
+        OUTPUT_STRIP_TRAILING_WHITESPACE)
+    set(${variable} ${result} PARENT_SCOPE)
+endfunction()
 
 if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
-    execute_process(COMMAND
-        ${get_part_info} --type data --subtype phy --offset ${PARTITION_CSV_PATH}
-        OUTPUT_VARIABLE PHY_PARTITION_OFFSET)
+    get_partition_info(PHY_PARTITION_OFFSET "--type data --subtype phy --offset")
     set(PHY_PARTITION_BIN_FILE "${CMAKE_BINARY_DIR}/esp32/phy_init_data.bin")
 endif()
 
-execute_process(COMMAND
-    ${get_part_info} --default-boot-partition --offset ${PARTITION_CSV_PATH}
-    OUTPUT_VARIABLE APP_PARTITION_OFFSET)
+get_partition_info(APP_PARTITION_OFFSET "--default-boot-partition --offset")
 
-execute_process(COMMAND
-    ${get_part_info} --type data --subtype ota --offset ${PARTITION_CSV_PATH}
-    OUTPUT_VARIABLE OTADATA_PARTITION_OFFSET)
+get_partition_info(OTADATA_PARTITION_OFFSET "--type data --subtype ota --offset")
 
-execute_process(COMMAND
-    ${get_part_info} --type data --subtype ota --size ${PARTITION_CSV_PATH}
-    OUTPUT_VARIABLE OTADATA_PARTITION_SIZE)
+get_partition_info(OTADATA_PARTITION_SIZE "--type data --subtype ota --size")
 
 endif()

From 393c29b6560483351c489483e89e83b0bd29885d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 20 Aug 2018 10:47:55 +1000
Subject: [PATCH 096/112] cmake: Fix bt component dependencies

---
 components/bt/CMakeLists.txt | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/components/bt/CMakeLists.txt b/components/bt/CMakeLists.txt
index 2a0941379..f64668f9f 100644
--- a/components/bt/CMakeLists.txt
+++ b/components/bt/CMakeLists.txt
@@ -82,10 +82,7 @@ if(CONFIG_BT_ENABLED)
 endif()
 
 # requirements can't depend on config
-set(COMPONENT_PRIV_REQUIRES lwip nvs_flash)
-
-# currently uses libcoap's hash table in hashkey.h
-set(COMPONENT_REQUIRES coap)
+set(COMPONENT_PRIV_REQUIRES nvs_flash)
 
 register_component()
 

From a56b3abf84432d2ff60cb71fff94fa2f01c60b27 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 20 Aug 2018 17:15:36 +1000
Subject: [PATCH 097/112] kconfiglib: Allow CONFIG_xxx= to disable booleans

But replace all sdkconfig.defaults to use the explicit =n (more correct)
---
 .../a2dp_gatts_coex/sdkconfig.defaults        | 22 +++++++++----------
 .../bluetooth/a2dp_sink/sdkconfig.defaults    |  8 +++----
 .../bluetooth/a2dp_source/sdkconfig.defaults  |  8 +++----
 examples/bluetooth/blufi/sdkconfig.defaults   | 22 +++++++++----------
 .../bluetooth/bt_discovery/sdkconfig.defaults |  8 +++----
 examples/wifi/iperf/sdkconfig.defaults        |  8 +++----
 tools/kconfig_new/kconfiglib.py               |  3 +++
 7 files changed, 41 insertions(+), 38 deletions(-)

diff --git a/examples/bluetooth/a2dp_gatts_coex/sdkconfig.defaults b/examples/bluetooth/a2dp_gatts_coex/sdkconfig.defaults
index 07275e1e7..8c4616123 100644
--- a/examples/bluetooth/a2dp_gatts_coex/sdkconfig.defaults
+++ b/examples/bluetooth/a2dp_gatts_coex/sdkconfig.defaults
@@ -2,29 +2,29 @@
 # Classic BT is enabled and BT_DRAM_RELEASE is disabled
 CONFIG_BT_ENABLED=y
 CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_0=y
-CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_1=
+CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_1=n
 CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE=0
 CONFIG_BTDM_CONTROLLER_HCI_MODE_VHCI=y
-CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4=
+CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4=n
 CONFIG_BLUEDROID_ENABLED=y
 CONFIG_BLUEDROID_PINNED_TO_CORE_0=y
-CONFIG_BLUEDROID_PINNED_TO_CORE_1=
+CONFIG_BLUEDROID_PINNED_TO_CORE_1=n
 CONFIG_BLUEDROID_PINNED_TO_CORE=0
 CONFIG_BTC_TASK_STACK_SIZE=3072
-CONFIG_BLUEDROID_MEM_DEBUG=
+CONFIG_BLUEDROID_MEM_DEBUG=n
 CONFIG_CLASSIC_BT_ENABLED=y
 CONFIG_A2DP_ENABLE=y
 CONFIG_A2DP_SINK_ENABLE=y
-CONFIG_A2DP_SRC_ENABLE=
+CONFIG_A2DP_SRC_ENABLE=n
 CONFIG_A2DP_SINK_TASK_STACK_SIZE=2048
-CONFIG_BT_SPP_ENABLED=
+CONFIG_BT_SPP_ENABLED=n
 CONFIG_GATTS_ENABLE=y
-CONFIG_GATTC_ENABLE=
-CONFIG_BLE_SMP_ENABLE=
+CONFIG_GATTC_ENABLE=n
+CONFIG_BLE_SMP_ENABLE=n
 CONFIG_BLE_ENABLE_SRVCHG_REG=y
-CONFIG_BT_STACK_NO_LOG=
+CONFIG_BT_STACK_NO_LOG=n
 CONFIG_BT_ACL_CONNECTIONS=4
-CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST=
-CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY=
+CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST=n
+CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY=n
 CONFIG_SMP_ENABLE=y
 CONFIG_BT_RESERVE_DRAM=0x10000
diff --git a/examples/bluetooth/a2dp_sink/sdkconfig.defaults b/examples/bluetooth/a2dp_sink/sdkconfig.defaults
index 82779f66e..9769836c2 100644
--- a/examples/bluetooth/a2dp_sink/sdkconfig.defaults
+++ b/examples/bluetooth/a2dp_sink/sdkconfig.defaults
@@ -4,7 +4,7 @@ CONFIG_BT_ENABLED=y
 CONFIG_BLUEDROID_ENABLED=y
 CONFIG_CLASSIC_BT_ENABLED=y
 CONFIG_A2DP_ENABLE=y
-CONFIG_BT_SPP_ENABLED=
-CONFIG_GATTS_ENABLE=
-CONFIG_GATTC_ENABLE=
-CONFIG_BLE_SMP_ENABLE=
+CONFIG_BT_SPP_ENABLED=n
+CONFIG_GATTS_ENABLE=n
+CONFIG_GATTC_ENABLE=n
+CONFIG_BLE_SMP_ENABLE=n
diff --git a/examples/bluetooth/a2dp_source/sdkconfig.defaults b/examples/bluetooth/a2dp_source/sdkconfig.defaults
index 6625f76f4..38b09494b 100644
--- a/examples/bluetooth/a2dp_source/sdkconfig.defaults
+++ b/examples/bluetooth/a2dp_source/sdkconfig.defaults
@@ -4,7 +4,7 @@ CONFIG_BT_ENABLED=y
 CONFIG_BLUEDROID_ENABLED=y
 CONFIG_CLASSIC_BT_ENABLED=y
 CONFIG_A2DP_ENABLE=y
-CONFIG_BT_SPP_ENABLED=
-CONFIG_GATTS_ENABLE=
-CONFIG_GATTC_ENABLE=
-CONFIG_BLE_SMP_ENABLE=
+CONFIG_BT_SPP_ENABLED=n
+CONFIG_GATTS_ENABLE=n
+CONFIG_GATTC_ENABLE=n
+CONFIG_BLE_SMP_ENABLE=n
diff --git a/examples/bluetooth/blufi/sdkconfig.defaults b/examples/bluetooth/blufi/sdkconfig.defaults
index a0d1d3652..2d73b0662 100644
--- a/examples/bluetooth/blufi/sdkconfig.defaults
+++ b/examples/bluetooth/blufi/sdkconfig.defaults
@@ -6,24 +6,24 @@
 #
 CONFIG_BT_ENABLED=y
 CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_0=y
-CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_1=
+CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE_1=n
 CONFIG_BTDM_CONTROLLER_PINNED_TO_CORE=0
 CONFIG_BTDM_CONTROLLER_HCI_MODE_VHCI=y
-CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4=
+CONFIG_BTDM_CONTROLLER_HCI_MODE_UART_H4=n
 CONFIG_BLUEDROID_ENABLED=y
 CONFIG_BLUEDROID_PINNED_TO_CORE_0=y
-CONFIG_BLUEDROID_PINNED_TO_CORE_1=
+CONFIG_BLUEDROID_PINNED_TO_CORE_1=n
 CONFIG_BLUEDROID_PINNED_TO_CORE=0
 CONFIG_BTC_TASK_STACK_SIZE=3072
-CONFIG_BLUEDROID_MEM_DEBUG=
-CONFIG_CLASSIC_BT_ENABLED=
+CONFIG_BLUEDROID_MEM_DEBUG=n
+CONFIG_CLASSIC_BT_ENABLED=n
 CONFIG_GATTS_ENABLE=y
-CONFIG_GATTC_ENABLE=
-CONFIG_BLE_SMP_ENABLE=
+CONFIG_GATTC_ENABLE=n
+CONFIG_BLE_SMP_ENABLE=n
 CONFIG_BLE_ENABLE_SRVCHG_REG=y
-CONFIG_BT_STACK_NO_LOG=
+CONFIG_BT_STACK_NO_LOG=n
 CONFIG_BT_ACL_CONNECTIONS=4
-CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST=
-CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY=
-CONFIG_SMP_ENABLE=
+CONFIG_BT_ALLOCATION_FROM_SPIRAM_FIRST=n
+CONFIG_BT_BLE_DYNAMIC_ENV_MEMORY=n
+CONFIG_SMP_ENABLE=n
 CONFIG_BT_RESERVE_DRAM=0x10000
diff --git a/examples/bluetooth/bt_discovery/sdkconfig.defaults b/examples/bluetooth/bt_discovery/sdkconfig.defaults
index ab028190f..793fe05c2 100644
--- a/examples/bluetooth/bt_discovery/sdkconfig.defaults
+++ b/examples/bluetooth/bt_discovery/sdkconfig.defaults
@@ -2,7 +2,7 @@
 # Classic BT is enabled and BT_DRAM_RELEASE is disabled
 CONFIG_BT_ENABLED=y
 CONFIG_CLASSIC_BT_ENABLED=y
-CONFIG_A2DP_ENABLE=
-CONFIG_GATTS_ENABLE=
-CONFIG_GATTC_ENABLE=
-CONFIG_BLE_SMP_ENABLE=
+CONFIG_A2DP_ENABLE=n
+CONFIG_GATTS_ENABLE=n
+CONFIG_GATTC_ENABLE=n
+CONFIG_BLE_SMP_ENABLE=n
diff --git a/examples/wifi/iperf/sdkconfig.defaults b/examples/wifi/iperf/sdkconfig.defaults
index 613b73f3f..f084e4a67 100644
--- a/examples/wifi/iperf/sdkconfig.defaults
+++ b/examples/wifi/iperf/sdkconfig.defaults
@@ -12,18 +12,18 @@ CONFIG_ESP32_WIFI_TX_BA_WIN=32
 CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED=y
 CONFIG_ESP32_WIFI_RX_BA_WIN=32
 
-CONFIG_FREERTOS_UNICORE=
+CONFIG_FREERTOS_UNICORE=n
 CONFIG_FREERTOS_HZ=1000
 
-CONFIG_INT_WDT=
-CONFIG_TASK_WDT=
+CONFIG_INT_WDT=n
+CONFIG_TASK_WDT=n
 
 CONFIG_TCP_SND_BUF_DEFAULT=65535
 CONFIG_TCP_WND_DEFAULT=65535
 CONFIG_TCP_RECVMBOX_SIZE=64
 CONFIG_UDP_RECVMBOX_SIZE=64
 CONFIG_TCPIP_RECVMBOX_SIZE=64
-CONFIG_LWIP_ETHARP_TRUST_IP_MAC=
+CONFIG_LWIP_ETHARP_TRUST_IP_MAC=n
 
 CONFIG_FLASHMODE_QIO=y
 CONFIG_ESPTOOLPY_FLASHFREQ_40M=y
diff --git a/tools/kconfig_new/kconfiglib.py b/tools/kconfig_new/kconfiglib.py
index 261e72e6b..929f30d4d 100644
--- a/tools/kconfig_new/kconfiglib.py
+++ b/tools/kconfig_new/kconfiglib.py
@@ -754,6 +754,9 @@ class Kconfig(object):
                         continue
 
                     if sym.orig_type in (BOOL, TRISTATE):
+                        if val == "":
+                            val = "n"  # C implementation allows 'blank' for 'no'
+
                         # The C implementation only checks the first character
                         # to the right of '=', for whatever reason
                         if not ((sym.orig_type == BOOL and

From 7f065438178036844f03e6fe121d4dd8810b0e01 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 20 Aug 2018 18:24:18 +1000
Subject: [PATCH 098/112] cmake/partitions: Apply offset to partition table
 metadata correctly

Also warn if the parttool.py has an error
---
 components/esptool_py/flasher_args.json.in       |  2 +-
 components/partition_table/CMakeLists.txt        |  2 +-
 components/partition_table/parttool.py           |  4 ++++
 components/partition_table/project_include.cmake | 13 +++++++++++--
 4 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
index ca591617a..4ec3a8c24 100644
--- a/components/esptool_py/flasher_args.json.in
+++ b/components/esptool_py/flasher_args.json.in
@@ -5,7 +5,7 @@
     "flash_files" : {
         "0x1000" : "bootloader/bootloader.bin",
         "${PARTITION_TABLE_OFFSET}" : "partition_table/partition-table.bin",
-        "${CONFIG_APP_OFFSET}" : "${PROJECT_NAME}.bin",
+        "${APP_PARTITION_OFFSET}" : "${PROJECT_NAME}.bin",
         "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}"
     },
     "bootloader" :      { "offset" : "0x1000",
diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index aa835c704..a97080c4c 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -23,7 +23,7 @@ if(CONFIG_ESPTOOLPY_FLASHSIZE)
 endif()
 
 add_custom_command(OUTPUT "${unsigned_partition_bin}"
-    COMMAND "${PYTHON}" "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py" -q ${md5_opt} ${flashsize_opt}
+    COMMAND "${PYTHON}" "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py" -q --offset ${PARTITION_TABLE_OFFSET} ${md5_opt} ${flashsize_opt}
     ${partition_csv} ${unsigned_partition_bin}
     DEPENDS ${partition_csv} "${CMAKE_CURRENT_SOURCE_DIR}/gen_esp32part.py"
     VERBATIM)
diff --git a/components/partition_table/parttool.py b/components/partition_table/parttool.py
index 8188dfe3d..145fb8d3c 100755
--- a/components/partition_table/parttool.py
+++ b/components/partition_table/parttool.py
@@ -49,6 +49,8 @@ def main():
 
     parser.add_argument('--quiet', '-q', help="Don't print status messages to stderr", action='store_true')
 
+    parser.add_argument('--partition-table-offset', help='The offset of the partition table in flash. Only consulted if partition table is in CSV format.', type=str, default='0x8000')
+
     search_type = parser.add_mutually_exclusive_group()
     search_type.add_argument('--partition-name', '-p', help='The name of the required partition', type=str, default=None)
     search_type.add_argument('--type', '-t', help='The type of the required partition', type=str, default=None)
@@ -74,6 +76,8 @@ def main():
 
     quiet = args.quiet
 
+    gen.offset_part_table = int(args.partition_table_offset, 0)
+
     input = args.input.read()
     input_is_binary = input[0:2] == gen.PartitionDefinition.MAGIC_BYTES
     if input_is_binary:
diff --git a/components/partition_table/project_include.cmake b/components/partition_table/project_include.cmake
index b09ffd358..8af1e0ee9 100644
--- a/components/partition_table/project_include.cmake
+++ b/components/partition_table/project_include.cmake
@@ -9,7 +9,8 @@ if(CONFIG_PARTITION_TABLE_CUSTOM)
     get_filename_component(PARTITION_CSV_PATH "${CONFIG_PARTITION_TABLE_FILENAME}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
 
     if(NOT EXISTS "${PARTITION_CSV_PATH}")
-        message(FATAL_ERROR "Partition table CSV file ${PARTITION_CSV_PATH} not found. Change custom partition CSV path in menuconfig.")
+        message(WARNING "Partition table CSV file ${PARTITION_CSV_PATH} not found. "
+            "Change custom partition CSV path in menuconfig.")
     endif()
 else()
     # Other .csv files are always in the component directory
@@ -27,9 +28,17 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${PARTITION_CSV_P
 function(get_partition_info variable get_part_info_args)
     separate_arguments(get_part_info_args)
     execute_process(COMMAND
-        ${COMPONENT_PATH}/parttool.py -q ${get_part_info_args} ${PARTITION_CSV_PATH}
+        ${COMPONENT_PATH}/parttool.py -q
+        --partition-table-offset ${PARTITION_TABLE_OFFSET}
+        ${get_part_info_args}
+        ${PARTITION_CSV_PATH}
         OUTPUT_VARIABLE result
+        RESULT_VARIABLE exit_code
         OUTPUT_STRIP_TRAILING_WHITESPACE)
+    if(NOT ${exit_code} EQUAL 0 AND NOT ${exit_code} EQUAL 1)
+        # can't fail here as it would prevent the user from running 'menuconfig' again
+        message(WARNING "parttool.py execution failed (${result}), problem with partition CSV file (see above)")
+    endif()
     set(${variable} ${result} PARENT_SCOPE)
 endfunction()
 

From 408463d0bfb11236d5d368d10e8b57e7ac7937ed Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 21 Aug 2018 10:13:02 +1000
Subject: [PATCH 099/112] cmake idf.py: Fix bug in JSON parsing when printing
 flash commands

---
 tools/idf.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tools/idf.py b/tools/idf.py
index abf098445..bb55ff59e 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -329,16 +329,17 @@ def print_closing_message(args):
         def flasher_path(f):
             return os.path.relpath(os.path.join(args.build_dir, f))
 
-        if key != "project":
+        if key != "project":  # flashing a single item
             cmd = ""
-            if key == "bootloader":
+            if key == "bootloader":  # bootloader needs --flash-mode, etc to be passed in
                 cmd = " ".join(flasher_args["write_flash_args"]) + " "
 
             cmd += flasher_args[key]["offset"] + " "
             cmd += flasher_path(flasher_args[key]["file"])
-        else:
+        else:  # flashing the whole project
             cmd = " ".join(flasher_args["write_flash_args"]) + " "
-            for o,f in flasher_args["flash_files"].items():
+            flash_items = sorted((o,f) for (o,f) in flasher_args["flash_files"].items() if len(o) > 0)
+            for o,f in flash_items:
                 cmd += o + " " + flasher_path(f) + " "
 
         print("%s -p %s -b %s write_flash %s" % (
@@ -346,7 +347,7 @@ def print_closing_message(args):
             args.port or "(PORT)",
             args.baud,
             cmd.strip()))
-        print("or run 'idf.py -p PORT %s'" % (key + "-flash" if key != "project" else "flash",))
+        print("or run 'idf.py -p %s %s'" % (args.port or "(PORT)", key + "-flash" if key != "project" else "flash",))
 
     if "all" in args.actions or "build" in args.actions:
         print_flashing_message("Project", "project")

From 071aaea66b4a7e310f8e6c754f3806e26aee7e48 Mon Sep 17 00:00:00 2001
From: Renz Bagaporo <renz@espressif.com>
Date: Tue, 21 Aug 2018 13:08:26 +0800
Subject: [PATCH 100/112] Place embedded data on flash

---
 tools/cmake/scripts/data_file_embed_asm.cmake | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/cmake/scripts/data_file_embed_asm.cmake b/tools/cmake/scripts/data_file_embed_asm.cmake
index 71329ade5..291f9fea2 100644
--- a/tools/cmake/scripts/data_file_embed_asm.cmake
+++ b/tools/cmake/scripts/data_file_embed_asm.cmake
@@ -67,6 +67,7 @@ endif()
 append_line(" */")
 
 append_line(".data")
+append_line(".section .rodata.embedded")
 append_identifier("${varname}")
 append_identifier("_binary_${varname}_start" "for objcopy compatibility")
 append("${data}")

From cb158f119467289db41705373908ed2104a1b2c8 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 27 Aug 2018 11:55:04 +0800
Subject: [PATCH 101/112] cmake: Account for missing partition CSV file at
 cmake runtime

Avoid either breaking menuconfig (if cmake fails), or producing bad build output (if cmake succeeds
but no flashing offsets, etc. were generated.)
---
 components/partition_table/CMakeLists.txt     | 19 ++++++++++++++++++-
 .../partition_table/project_include.cmake     |  2 ++
 tools/cmake/scripts/fail.cmake                |  4 ++++
 3 files changed, 24 insertions(+), 1 deletion(-)
 create mode 100644 tools/cmake/scripts/fail.cmake

diff --git a/components/partition_table/CMakeLists.txt b/components/partition_table/CMakeLists.txt
index a97080c4c..443a5ad6e 100644
--- a/components/partition_table/CMakeLists.txt
+++ b/components/partition_table/CMakeLists.txt
@@ -42,7 +42,24 @@ if(CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES)
 
 endif()
 
-add_custom_target(partition_table ALL DEPENDS "${final_partition_bin}")
+if(EXISTS ${partition_csv})
+    add_custom_target(partition_table ALL DEPENDS "${final_partition_bin}")
+else()
+    # This is a bit of a hack: If the partition input CSV is not found, create a phony partition_table target that
+    # fails the build. Have it also touch CMakeCache.txt to cause a cmake run next time
+    # (to pick up a new CSV if one exists, etc.)
+    #
+    # This is because partition CSV is required at CMake runtime (to generate metadata files with flashing data, etc) but we can't
+    # fail the build if it is not found, because the "menuconfig" target may be required to fix the problem. CMAKE_CONFIGURE_DEPENDS
+    # only works for files which exist at CMake runtime.
+    add_custom_target(partition_table ALL
+        COMMAND ${CMAKE_COMMAND} -E echo "Partition table CSV ${partition_csv} does not exist. Either change partition table in menuconfig or create this input file."
+        COMMAND ${CMAKE_COMMAND} -E touch "${CMAKE_BINARY_DIR}/CMakeCache.txt"
+        COMMAND ${CMAKE_COMMAND} -P ${IDF_PATH}/tools/cmake/scripts/fail.cmake)
+endif()
+
+add_dependencies(bootloader partition_table)
+add_dependencies(app partition_table)
 
 # Use global properties ESPTOOL_WRITE_FLASH_ARGS to pass this info to build
 # the list of esptool write arguments for flashing
diff --git a/components/partition_table/project_include.cmake b/components/partition_table/project_include.cmake
index 8af1e0ee9..07ba2cce0 100644
--- a/components/partition_table/project_include.cmake
+++ b/components/partition_table/project_include.cmake
@@ -11,6 +11,8 @@ if(CONFIG_PARTITION_TABLE_CUSTOM)
     if(NOT EXISTS "${PARTITION_CSV_PATH}")
         message(WARNING "Partition table CSV file ${PARTITION_CSV_PATH} not found. "
             "Change custom partition CSV path in menuconfig.")
+        # Note: partition_table CMakeLists.txt contains some logic to create a dummy
+        # partition_table target in this case, see comments in that file.
     endif()
 else()
     # Other .csv files are always in the component directory
diff --git a/tools/cmake/scripts/fail.cmake b/tools/cmake/scripts/fail.cmake
new file mode 100644
index 000000000..5ceddb3ca
--- /dev/null
+++ b/tools/cmake/scripts/fail.cmake
@@ -0,0 +1,4 @@
+# 'cmake -E' doesn't have a way to fail outright, so run this script
+# with 'cmake -P' to fail a build.
+message(FATAL_ERROR "Failing the build (see errors on lines above)")
+

From a528d3a61aebdc3ccc8675c63d239a8471aa9a23 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 27 Aug 2018 17:24:31 +0800
Subject: [PATCH 102/112] kconfig: Merge Kconfig.compiler back into Kconfig

Reverts 5e0a3d99e8f748dab2b313339ba9b3ab6abd1640 (no longer needed but also not supported by
mconf-idf built from kconfig-frontends repo.)
---
 Kconfig          | 136 ++++++++++++++++++++++++++++++++++++++++++++++-
 Kconfig.compiler | 135 ----------------------------------------------
 2 files changed, 135 insertions(+), 136 deletions(-)
 delete mode 100644 Kconfig.compiler

diff --git a/Kconfig b/Kconfig
index 76a9e57c3..ff1a6d017 100644
--- a/Kconfig
+++ b/Kconfig
@@ -42,7 +42,141 @@ endmenu  # SDK tool configuration
 
 source "$COMPONENT_KCONFIGS_PROJBUILD"
 
-source "$IDF_PATH/Kconfig.compiler"
+menu "Compiler options"
+
+choice OPTIMIZATION_COMPILER
+    prompt "Optimization Level"
+    default OPTIMIZATION_LEVEL_DEBUG
+    help
+        This option sets compiler optimization level (gcc -O argument).
+
+        - for "Release" setting, -Os flag is added to CFLAGS.
+        - for "Debug" setting, -Og flag is added to CFLAGS.
+
+        "Release" with -Os produces smaller & faster compiled code but it
+        may be harder to correlated code addresses to source files when debugging.
+
+        To add custom optimization settings, set CFLAGS and/or CPPFLAGS
+        in project makefile, before including $(IDF_PATH)/make/project.mk. Note that
+        custom optimization levels may be unsupported.
+
+config OPTIMIZATION_LEVEL_DEBUG
+    bool "Debug (-Og)"
+config OPTIMIZATION_LEVEL_RELEASE
+    bool "Release (-Os)"
+endchoice
+
+choice OPTIMIZATION_ASSERTION_LEVEL
+    prompt "Assertion level"
+    default OPTIMIZATION_ASSERTIONS_ENABLED
+    help
+        Assertions can be:
+
+        - Enabled. Failure will print verbose assertion details. This is the default.
+
+        - Set to "silent" to save code size (failed assertions will abort() but user
+          needs to use the aborting address to find the line number with the failed assertion.)
+
+        - Disabled entirely (not recommended for most configurations.) -DNDEBUG is added
+          to CPPFLAGS in this case.
+
+config OPTIMIZATION_ASSERTIONS_ENABLED
+    prompt "Enabled"
+    bool
+    help
+        Enable assertions. Assertion content and line number will be printed on failure.
+
+config OPTIMIZATION_ASSERTIONS_SILENT
+    prompt "Silent (saves code size)"
+    bool
+    help
+        Enable silent assertions. Failed assertions will abort(), user needs to
+        use the aborting address to find the line number with the failed assertion.
+
+config OPTIMIZATION_ASSERTIONS_DISABLED
+    prompt "Disabled (sets -DNDEBUG)"
+    bool
+    help
+        If assertions are disabled, -DNDEBUG is added to CPPFLAGS.
+
+endchoice # assertions
+
+menuconfig CXX_EXCEPTIONS
+   bool "Enable C++ exceptions"
+   default n
+   help
+       Enabling this option compiles all IDF C++ files with exception support enabled.
+
+       Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which throws
+       an exception will abort instead.
+
+       Enabling this option currently adds an additional ~500 bytes of heap overhead
+       when an exception is thrown in user code for the first time.
+
+config CXX_EXCEPTIONS_EMG_POOL_SIZE
+    int "Emergency Pool Size"
+    default 0
+    depends on CXX_EXCEPTIONS
+    help
+       Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate
+       memory for thrown exceptions when there is not enough memory on the heap.
+
+choice STACK_CHECK_MODE
+    prompt "Stack smashing protection mode"
+    default STACK_CHECK_NONE
+    help
+        Stack smashing protection mode. Emit extra code to check for buffer overflows, such as stack
+        smashing attacks. This is done by adding a guard variable to functions with vulnerable objects.
+        The guards are initialized when a function is entered and then checked when the function exits.
+        If a guard check fails, program is halted. Protection has the following modes:
+
+        - In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca,
+          and functions with buffers larger than 8 bytes are protected.
+        
+        - STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes
+          additional functions to be protected -- those that have local array definitions,
+          or have references to local frame addresses.
+        
+        - In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected.
+
+        Modes have the following impact on code performance and coverage:
+
+        - performance: NORMAL > STRONG > OVERALL
+        
+        - coverage: NORMAL < STRONG < OVERALL
+
+
+config STACK_CHECK_NONE
+    bool "None"
+config STACK_CHECK_NORM
+    bool "Normal"
+config STACK_CHECK_STRONG
+    bool "Strong"
+config STACK_CHECK_ALL
+    bool "Overall"
+endchoice
+
+config STACK_CHECK
+    bool
+    default !STACK_CHECK_NONE
+    help
+        Stack smashing protection.
+
+config WARN_WRITE_STRINGS
+    bool "Enable -Wwrite-strings warning flag"
+    default "n"
+    help
+        Adds -Wwrite-strings flag for the C/C++ compilers.
+
+        For C, this gives string constants the type ``const char[]`` so that
+        copying the address of one into a non-const ``char *`` pointer
+        produces a warning. This warning helps to find at compile time code
+        that tries to write into a string constant.
+
+        For C++, this warns about the deprecated conversion from string
+        literals to ``char *``.
+
+endmenu # Compiler Options
 
 menu "Component config"
 source "$COMPONENT_KCONFIGS"
diff --git a/Kconfig.compiler b/Kconfig.compiler
deleted file mode 100644
index ab689e88f..000000000
--- a/Kconfig.compiler
+++ /dev/null
@@ -1,135 +0,0 @@
-menu "Compiler options"
-
-choice OPTIMIZATION_COMPILER
-    prompt "Optimization Level"
-    default OPTIMIZATION_LEVEL_DEBUG
-    help
-        This option sets compiler optimization level (gcc -O argument).
-
-        - for "Release" setting, -Os flag is added to CFLAGS.
-        - for "Debug" setting, -Og flag is added to CFLAGS.
-
-        "Release" with -Os produces smaller & faster compiled code but it
-        may be harder to correlated code addresses to source files when debugging.
-
-        To add custom optimization settings, set CFLAGS and/or CPPFLAGS
-        in project makefile, before including $(IDF_PATH)/make/project.mk. Note that
-        custom optimization levels may be unsupported.
-
-config OPTIMIZATION_LEVEL_DEBUG
-    bool "Debug (-Og)"
-config OPTIMIZATION_LEVEL_RELEASE
-    bool "Release (-Os)"
-endchoice
-
-choice OPTIMIZATION_ASSERTION_LEVEL
-    prompt "Assertion level"
-    default OPTIMIZATION_ASSERTIONS_ENABLED
-    help
-        Assertions can be:
-
-        - Enabled. Failure will print verbose assertion details. This is the default.
-
-        - Set to "silent" to save code size (failed assertions will abort() but user
-          needs to use the aborting address to find the line number with the failed assertion.)
-
-        - Disabled entirely (not recommended for most configurations.) -DNDEBUG is added
-          to CPPFLAGS in this case.
-
-config OPTIMIZATION_ASSERTIONS_ENABLED
-    prompt "Enabled"
-    bool
-    help
-        Enable assertions. Assertion content and line number will be printed on failure.
-
-config OPTIMIZATION_ASSERTIONS_SILENT
-    prompt "Silent (saves code size)"
-    bool
-    help
-        Enable silent assertions. Failed assertions will abort(), user needs to
-        use the aborting address to find the line number with the failed assertion.
-
-config OPTIMIZATION_ASSERTIONS_DISABLED
-    prompt "Disabled (sets -DNDEBUG)"
-    bool
-    help
-        If assertions are disabled, -DNDEBUG is added to CPPFLAGS.
-
-endchoice # assertions
-
-menuconfig CXX_EXCEPTIONS
-   bool "Enable C++ exceptions"
-   default n
-   help
-       Enabling this option compiles all IDF C++ files with exception support enabled.
-
-       Disabling this option disables C++ exception support in all compiled files, and any libstdc++ code which throws
-       an exception will abort instead.
-
-       Enabling this option currently adds an additional ~500 bytes of heap overhead
-       when an exception is thrown in user code for the first time.
-
-config CXX_EXCEPTIONS_EMG_POOL_SIZE
-    int "Emergency Pool Size"
-    default 0
-    depends on CXX_EXCEPTIONS
-    help
-       Size (in bytes) of the emergency memory pool for C++ exceptions. This pool will be used to allocate
-       memory for thrown exceptions when there is not enough memory on the heap.
-
-choice STACK_CHECK_MODE
-    prompt "Stack smashing protection mode"
-    default STACK_CHECK_NONE
-    help
-        Stack smashing protection mode. Emit extra code to check for buffer overflows, such as stack
-        smashing attacks. This is done by adding a guard variable to functions with vulnerable objects.
-        The guards are initialized when a function is entered and then checked when the function exits.
-        If a guard check fails, program is halted. Protection has the following modes:
-
-        - In NORMAL mode (GCC flag: -fstack-protector) only functions that call alloca,
-          and functions with buffers larger than 8 bytes are protected.
-        
-        - STRONG mode (GCC flag: -fstack-protector-strong) is like NORMAL, but includes
-          additional functions to be protected -- those that have local array definitions,
-          or have references to local frame addresses.
-        
-        - In OVERALL mode (GCC flag: -fstack-protector-all) all functions are protected.
-
-        Modes have the following impact on code performance and coverage:
-
-        - performance: NORMAL > STRONG > OVERALL
-        
-        - coverage: NORMAL < STRONG < OVERALL
-
-
-config STACK_CHECK_NONE
-    bool "None"
-config STACK_CHECK_NORM
-    bool "Normal"
-config STACK_CHECK_STRONG
-    bool "Strong"
-config STACK_CHECK_ALL
-    bool "Overall"
-endchoice
-
-config STACK_CHECK
-    bool
-    default !STACK_CHECK_NONE
-    help
-        Stack smashing protection.
-
-config WARN_WRITE_STRINGS
-    bool "Enable -Wwrite-strings warning flag"
-    default "n"
-    help
-        Adds -Wwrite-strings flag for the C/C++ compilers.
-
-        For C, this gives string constants the type ``const char[]`` so that
-        copying the address of one into a non-const ``char *`` pointer
-        produces a warning. This warning helps to find at compile time code
-        that tries to write into a string constant.
-
-        For C++, this warns about the deprecated conversion from string
-        literals to ``char *``.
-
-endmenu # Compiler Options

From 49a910adfb81c049a95bf661ff7f0ce04dcf8a93 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 27 Aug 2018 18:02:30 +0800
Subject: [PATCH 103/112] cmake: partition_table: Use PYTHON interpreter when
 running parttool.py (fixes flasher args on Windows)

---
 components/partition_table/project_include.cmake | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/partition_table/project_include.cmake b/components/partition_table/project_include.cmake
index 07ba2cce0..014426472 100644
--- a/components/partition_table/project_include.cmake
+++ b/components/partition_table/project_include.cmake
@@ -29,7 +29,7 @@ set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${PARTITION_CSV_P
 # Parse the partition table to get variable partition offsets & sizes which must be known at CMake runtime
 function(get_partition_info variable get_part_info_args)
     separate_arguments(get_part_info_args)
-    execute_process(COMMAND
+    execute_process(COMMAND ${PYTHON}
         ${COMPONENT_PATH}/parttool.py -q
         --partition-table-offset ${PARTITION_TABLE_OFFSET}
         ${get_part_info_args}

From 5689e446dc92000b25cbe746355b217e3547b16b Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 28 Aug 2018 11:10:48 +0800
Subject: [PATCH 104/112] cmake: Add missing example CMakeLists.txt files, CI
 check all examples have both

---
 .gitlab-ci.yml                                | 14 +++++++++++
 .../bluetooth/a2dp_gatts_coex/CMakeLists.txt  | 12 ++++++++++
 .../ble_hid_device_demo/CMakeLists.txt        | 11 +++++++++
 .../get-started/hello_world/partitions.csv    |  5 ++++
 .../can/can_alert_and_recovery/CMakeLists.txt |  8 +++++++
 .../can_network_listen_only/CMakeLists.txt    |  8 +++++++
 .../can_network_master/CMakeLists.txt         |  8 +++++++
 .../can_network_slave/CMakeLists.txt          |  8 +++++++
 .../can/can_self_test/CMakeLists.txt          |  8 +++++++
 .../mcpwm/mcpwm_basic_config/CMakeLists.txt   |  8 +++++++
 .../mcpwm/mcpwm_bldc_control/CMakeLists.txt   |  8 +++++++
 .../mcpwm_brushed_dc_control/CMakeLists.txt   |  8 +++++++
 .../mcpwm/mcpwm_servo_control/CMakeLists.txt  |  8 +++++++
 .../sdio/host}/CMakeLists.txt                 |  4 ++--
 .../host/components/esp_slave/CMakeLists.txt  |  6 +++++
 .../peripherals/sdio/slave/CMakeLists.txt     |  8 +++++++
 .../spi_slave/receiver/CMakeLists.txt         |  8 +++++++
 .../spi_slave/sender/CMakeLists.txt           |  8 +++++++
 .../uart_echo_rs485/CMakeLists.txt            |  8 +++++++
 .../protocols/asio/chat_client/CMakeLists.txt |  8 +++++++
 .../chat_client/components/CMakeLists.txt     |  5 ++++
 .../protocols/asio/chat_server/CMakeLists.txt |  8 +++++++
 .../chat_server/components/CMakeLists.txt     |  5 ++++
 .../asio/tcp_echo_server/CMakeLists.txt       |  8 +++++++
 .../tcp_echo_server/components/CMakeLists.txt |  5 ++++
 .../asio/udp_echo_server/CMakeLists.txt       |  8 +++++++
 .../udp_echo_server/components/CMakeLists.txt |  5 ++++
 .../http_server/advanced_tests/CMakeLists.txt | 10 ++++++++
 .../persistent_sockets/CMakeLists.txt         |  9 +++++++
 .../http_server/simple/CMakeLists.txt         | 10 ++++++++
 .../protocols/https_mbedtls/CMakeLists.txt    | 14 +++++++++++
 examples/system/esp_timer/CMakeLists.txt      |  8 +++++++
 .../ota/native_ota_example/CMakeLists.txt     | 14 +++++++++++
 .../ota/simple_ota_example/CMakeLists.txt     | 14 +++++++++++
 examples/wifi/simple_wifi/CMakeLists.txt      |  8 +++++++
 tools/ci/check_examples_cmake_make.sh         | 24 +++++++++++++++++++
 tools/ci/executable-list.txt                  |  1 +
 37 files changed, 318 insertions(+), 2 deletions(-)
 create mode 100644 examples/bluetooth/a2dp_gatts_coex/CMakeLists.txt
 create mode 100644 examples/bluetooth/ble_hid_device_demo/CMakeLists.txt
 create mode 100644 examples/get-started/hello_world/partitions.csv
 create mode 100644 examples/peripherals/can/can_alert_and_recovery/CMakeLists.txt
 create mode 100644 examples/peripherals/can/can_network/can_network_listen_only/CMakeLists.txt
 create mode 100644 examples/peripherals/can/can_network/can_network_master/CMakeLists.txt
 create mode 100644 examples/peripherals/can/can_network/can_network_slave/CMakeLists.txt
 create mode 100644 examples/peripherals/can/can_self_test/CMakeLists.txt
 create mode 100644 examples/peripherals/mcpwm/mcpwm_basic_config/CMakeLists.txt
 create mode 100644 examples/peripherals/mcpwm/mcpwm_bldc_control/CMakeLists.txt
 create mode 100644 examples/peripherals/mcpwm/mcpwm_brushed_dc_control/CMakeLists.txt
 create mode 100644 examples/peripherals/mcpwm/mcpwm_servo_control/CMakeLists.txt
 rename examples/{system/ota => peripherals/sdio/host}/CMakeLists.txt (80%)
 create mode 100644 examples/peripherals/sdio/host/components/esp_slave/CMakeLists.txt
 create mode 100644 examples/peripherals/sdio/slave/CMakeLists.txt
 create mode 100644 examples/peripherals/spi_slave/receiver/CMakeLists.txt
 create mode 100644 examples/peripherals/spi_slave/sender/CMakeLists.txt
 create mode 100644 examples/peripherals/uart_echo_rs485/CMakeLists.txt
 create mode 100644 examples/protocols/asio/chat_client/CMakeLists.txt
 create mode 100644 examples/protocols/asio/chat_client/components/CMakeLists.txt
 create mode 100644 examples/protocols/asio/chat_server/CMakeLists.txt
 create mode 100644 examples/protocols/asio/chat_server/components/CMakeLists.txt
 create mode 100644 examples/protocols/asio/tcp_echo_server/CMakeLists.txt
 create mode 100644 examples/protocols/asio/tcp_echo_server/components/CMakeLists.txt
 create mode 100644 examples/protocols/asio/udp_echo_server/CMakeLists.txt
 create mode 100644 examples/protocols/asio/udp_echo_server/components/CMakeLists.txt
 create mode 100644 examples/protocols/http_server/advanced_tests/CMakeLists.txt
 create mode 100644 examples/protocols/http_server/persistent_sockets/CMakeLists.txt
 create mode 100644 examples/protocols/http_server/simple/CMakeLists.txt
 create mode 100644 examples/protocols/https_mbedtls/CMakeLists.txt
 create mode 100644 examples/system/esp_timer/CMakeLists.txt
 create mode 100644 examples/system/ota/native_ota_example/CMakeLists.txt
 create mode 100644 examples/system/ota/simple_ota_example/CMakeLists.txt
 create mode 100644 examples/wifi/simple_wifi/CMakeLists.txt
 create mode 100755 tools/ci/check_examples_cmake_make.sh

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 4e5b1e3b8..5bf67bb9c 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -519,6 +519,20 @@ check_permissions:
   script:
     - tools/ci/check-executable.sh
 
+check_examples_cmake_make:
+  stage: deploy
+  image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
+  tags:
+    - build
+  except:
+    - master
+    - /^release\/v/
+    - /^v\d+\.\d+(\.\d+)?($|-)/
+  dependencies: []
+  before_script: *do_nothing_before
+  script:
+    - tools/ci/check_examples_cmake_make.sh
+
 check_submodule_sync:
   stage: deploy
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
diff --git a/examples/bluetooth/a2dp_gatts_coex/CMakeLists.txt b/examples/bluetooth/a2dp_gatts_coex/CMakeLists.txt
new file mode 100644
index 000000000..3243515f3
--- /dev/null
+++ b/examples/bluetooth/a2dp_gatts_coex/CMakeLists.txt
@@ -0,0 +1,12 @@
+# The following lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS
+    main/bt_app_av.c
+    main/bt_app_core.c
+    main/main.c
+    )
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(bt_ble_coex)
diff --git a/examples/bluetooth/ble_hid_device_demo/CMakeLists.txt b/examples/bluetooth/ble_hid_device_demo/CMakeLists.txt
new file mode 100644
index 000000000..9cacc3489
--- /dev/null
+++ b/examples/bluetooth/ble_hid_device_demo/CMakeLists.txt
@@ -0,0 +1,11 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/ble_hidd_demo_main.c
+    main/hid_dev.c
+    main/hid_device_le_prf.c
+    main/esp_hidd_prf_api.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(hidd_demos)
diff --git a/examples/get-started/hello_world/partitions.csv b/examples/get-started/hello_world/partitions.csv
new file mode 100644
index 000000000..22cf97bac
--- /dev/null
+++ b/examples/get-started/hello_world/partitions.csv
@@ -0,0 +1,5 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+# Note: if you change the phy_init or app partition offset, make sure to change the offset in Kconfig.projbuild
+nvs,      data, nvs,     ,        0x6000,
+phy_init, data, phy,     ,        0x1000,
+factory,  app,  factory, ,        1M,
diff --git a/examples/peripherals/can/can_alert_and_recovery/CMakeLists.txt b/examples/peripherals/can/can_alert_and_recovery/CMakeLists.txt
new file mode 100644
index 000000000..c5e43497c
--- /dev/null
+++ b/examples/peripherals/can/can_alert_and_recovery/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/can_alert_and_recovery_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(can_alert_and_recovery_example)
diff --git a/examples/peripherals/can/can_network/can_network_listen_only/CMakeLists.txt b/examples/peripherals/can/can_network/can_network_listen_only/CMakeLists.txt
new file mode 100644
index 000000000..3f0f7a1c0
--- /dev/null
+++ b/examples/peripherals/can/can_network/can_network_listen_only/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/can_network_example_listen_only_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(can_network_listen_only)
diff --git a/examples/peripherals/can/can_network/can_network_master/CMakeLists.txt b/examples/peripherals/can/can_network/can_network_master/CMakeLists.txt
new file mode 100644
index 000000000..f64b5e445
--- /dev/null
+++ b/examples/peripherals/can/can_network/can_network_master/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/can_network_example_master_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(can_network_master)
diff --git a/examples/peripherals/can/can_network/can_network_slave/CMakeLists.txt b/examples/peripherals/can/can_network/can_network_slave/CMakeLists.txt
new file mode 100644
index 000000000..4c7f9c933
--- /dev/null
+++ b/examples/peripherals/can/can_network/can_network_slave/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/can_network_example_slave_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(can_network_slave)
diff --git a/examples/peripherals/can/can_self_test/CMakeLists.txt b/examples/peripherals/can/can_self_test/CMakeLists.txt
new file mode 100644
index 000000000..c6ab8e924
--- /dev/null
+++ b/examples/peripherals/can/can_self_test/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/can_self_test_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(can_self_test_example)
diff --git a/examples/peripherals/mcpwm/mcpwm_basic_config/CMakeLists.txt b/examples/peripherals/mcpwm/mcpwm_basic_config/CMakeLists.txt
new file mode 100644
index 000000000..a3ee8315f
--- /dev/null
+++ b/examples/peripherals/mcpwm/mcpwm_basic_config/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/mcpwm_basic_config_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mcpwm_basic_config)
diff --git a/examples/peripherals/mcpwm/mcpwm_bldc_control/CMakeLists.txt b/examples/peripherals/mcpwm/mcpwm_bldc_control/CMakeLists.txt
new file mode 100644
index 000000000..ed09e85b2
--- /dev/null
+++ b/examples/peripherals/mcpwm/mcpwm_bldc_control/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/mcpwm_bldc_control_hall_sensor_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mcpwm_bldc_control_hall_sensor)
diff --git a/examples/peripherals/mcpwm/mcpwm_brushed_dc_control/CMakeLists.txt b/examples/peripherals/mcpwm/mcpwm_brushed_dc_control/CMakeLists.txt
new file mode 100644
index 000000000..4076c2839
--- /dev/null
+++ b/examples/peripherals/mcpwm/mcpwm_brushed_dc_control/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/mcpwm_brushed_dc_control_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mcpwm_brushed_dc_control)
diff --git a/examples/peripherals/mcpwm/mcpwm_servo_control/CMakeLists.txt b/examples/peripherals/mcpwm/mcpwm_servo_control/CMakeLists.txt
new file mode 100644
index 000000000..fc3fab809
--- /dev/null
+++ b/examples/peripherals/mcpwm/mcpwm_servo_control/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/mcpwm_servo_control_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(mcpwm_servo_control)
diff --git a/examples/system/ota/CMakeLists.txt b/examples/peripherals/sdio/host/CMakeLists.txt
similarity index 80%
rename from examples/system/ota/CMakeLists.txt
rename to examples/peripherals/sdio/host/CMakeLists.txt
index 0b66883d1..507af55e7 100644
--- a/examples/system/ota/CMakeLists.txt
+++ b/examples/peripherals/sdio/host/CMakeLists.txt
@@ -2,7 +2,7 @@
 # in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
-set(MAIN_SRCS main/ota_example_main.c)
+set(MAIN_SRCS main/app_main.c)
 
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
-project(ota)
+project(sdio_host)
diff --git a/examples/peripherals/sdio/host/components/esp_slave/CMakeLists.txt b/examples/peripherals/sdio/host/components/esp_slave/CMakeLists.txt
new file mode 100644
index 000000000..c864bbba2
--- /dev/null
+++ b/examples/peripherals/sdio/host/components/esp_slave/CMakeLists.txt
@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES driver sdmmc)
+
+register_component()
diff --git a/examples/peripherals/sdio/slave/CMakeLists.txt b/examples/peripherals/sdio/slave/CMakeLists.txt
new file mode 100644
index 000000000..f5d89e6d0
--- /dev/null
+++ b/examples/peripherals/sdio/slave/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/app_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(sdio_slave)
diff --git a/examples/peripherals/spi_slave/receiver/CMakeLists.txt b/examples/peripherals/spi_slave/receiver/CMakeLists.txt
new file mode 100644
index 000000000..21c05d9e6
--- /dev/null
+++ b/examples/peripherals/spi_slave/receiver/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/app_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spi-slave-receiver)
diff --git a/examples/peripherals/spi_slave/sender/CMakeLists.txt b/examples/peripherals/spi_slave/sender/CMakeLists.txt
new file mode 100644
index 000000000..0c95698e9
--- /dev/null
+++ b/examples/peripherals/spi_slave/sender/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/app_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(spi-slave-sender)
diff --git a/examples/peripherals/uart_echo_rs485/CMakeLists.txt b/examples/peripherals/uart_echo_rs485/CMakeLists.txt
new file mode 100644
index 000000000..7df245118
--- /dev/null
+++ b/examples/peripherals/uart_echo_rs485/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/rs485_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(echo_rs485)
diff --git a/examples/protocols/asio/chat_client/CMakeLists.txt b/examples/protocols/asio/chat_client/CMakeLists.txt
new file mode 100644
index 000000000..78d29f0bd
--- /dev/null
+++ b/examples/protocols/asio/chat_client/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/chat_client.cpp)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(asio_chat_client)
diff --git a/examples/protocols/asio/chat_client/components/CMakeLists.txt b/examples/protocols/asio/chat_client/components/CMakeLists.txt
new file mode 100644
index 000000000..4bb51e6a5
--- /dev/null
+++ b/examples/protocols/asio/chat_client/components/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+
+set(COMPONENT_PRIV_REQUIRES asio nvs_flash console)
+
+register_component()
diff --git a/examples/protocols/asio/chat_server/CMakeLists.txt b/examples/protocols/asio/chat_server/CMakeLists.txt
new file mode 100644
index 000000000..91331df14
--- /dev/null
+++ b/examples/protocols/asio/chat_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/chat_server.cpp)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(asio_chat_server)
diff --git a/examples/protocols/asio/chat_server/components/CMakeLists.txt b/examples/protocols/asio/chat_server/components/CMakeLists.txt
new file mode 100644
index 000000000..4bb51e6a5
--- /dev/null
+++ b/examples/protocols/asio/chat_server/components/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+
+set(COMPONENT_PRIV_REQUIRES asio nvs_flash console)
+
+register_component()
diff --git a/examples/protocols/asio/tcp_echo_server/CMakeLists.txt b/examples/protocols/asio/tcp_echo_server/CMakeLists.txt
new file mode 100644
index 000000000..76bf9bcb6
--- /dev/null
+++ b/examples/protocols/asio/tcp_echo_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/echo_server.cpp)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(asio_tcp_echo_server)
diff --git a/examples/protocols/asio/tcp_echo_server/components/CMakeLists.txt b/examples/protocols/asio/tcp_echo_server/components/CMakeLists.txt
new file mode 100644
index 000000000..4bb51e6a5
--- /dev/null
+++ b/examples/protocols/asio/tcp_echo_server/components/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+
+set(COMPONENT_PRIV_REQUIRES asio nvs_flash console)
+
+register_component()
diff --git a/examples/protocols/asio/udp_echo_server/CMakeLists.txt b/examples/protocols/asio/udp_echo_server/CMakeLists.txt
new file mode 100644
index 000000000..143a364e4
--- /dev/null
+++ b/examples/protocols/asio/udp_echo_server/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/udp_echo_server.cpp)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(asio_udp_echo_server)
diff --git a/examples/protocols/asio/udp_echo_server/components/CMakeLists.txt b/examples/protocols/asio/udp_echo_server/components/CMakeLists.txt
new file mode 100644
index 000000000..4bb51e6a5
--- /dev/null
+++ b/examples/protocols/asio/udp_echo_server/components/CMakeLists.txt
@@ -0,0 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+
+set(COMPONENT_PRIV_REQUIRES asio nvs_flash console)
+
+register_component()
diff --git a/examples/protocols/http_server/advanced_tests/CMakeLists.txt b/examples/protocols/http_server/advanced_tests/CMakeLists.txt
new file mode 100644
index 000000000..6edb47bda
--- /dev/null
+++ b/examples/protocols/http_server/advanced_tests/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/tests.c main/main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(tests)
+
+target_include_directories(tests.elf PRIVATE main/include)
diff --git a/examples/protocols/http_server/persistent_sockets/CMakeLists.txt b/examples/protocols/http_server/persistent_sockets/CMakeLists.txt
new file mode 100644
index 000000000..b3587a5ef
--- /dev/null
+++ b/examples/protocols/http_server/persistent_sockets/CMakeLists.txt
@@ -0,0 +1,9 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(persistent_sockets)
+
diff --git a/examples/protocols/http_server/simple/CMakeLists.txt b/examples/protocols/http_server/simple/CMakeLists.txt
new file mode 100644
index 000000000..0b6dc948c
--- /dev/null
+++ b/examples/protocols/http_server/simple/CMakeLists.txt
@@ -0,0 +1,10 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(simple)
+
+
diff --git a/examples/protocols/https_mbedtls/CMakeLists.txt b/examples/protocols/https_mbedtls/CMakeLists.txt
new file mode 100644
index 000000000..b564db2fa
--- /dev/null
+++ b/examples/protocols/https_mbedtls/CMakeLists.txt
@@ -0,0 +1,14 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/https_mbedtls_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(https-mbedtls)
+
+# Embed the server root certificate into the final binary
+#
+# (If this was a component, we would set COMPONENT_EMBED_TXTFILES here.)
+target_add_binary_data(https-mbedtls.elf
+    "main/server_root_cert.pem" TEXT)
diff --git a/examples/system/esp_timer/CMakeLists.txt b/examples/system/esp_timer/CMakeLists.txt
new file mode 100644
index 000000000..5165f3d2a
--- /dev/null
+++ b/examples/system/esp_timer/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/esp_timer_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(esp_timer_example)
diff --git a/examples/system/ota/native_ota_example/CMakeLists.txt b/examples/system/ota/native_ota_example/CMakeLists.txt
new file mode 100644
index 000000000..c4aa4d0d4
--- /dev/null
+++ b/examples/system/ota/native_ota_example/CMakeLists.txt
@@ -0,0 +1,14 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/native_ota_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(native_ota)
+
+# Embed the server root certificate into the final binary
+#
+# (If this was a component, we would set COMPONENT_EMBED_TXTFILES here.)
+target_add_binary_data(native_ota.elf
+    "../server_certs/ca_cert.pem" TEXT)
diff --git a/examples/system/ota/simple_ota_example/CMakeLists.txt b/examples/system/ota/simple_ota_example/CMakeLists.txt
new file mode 100644
index 000000000..f15e70874
--- /dev/null
+++ b/examples/system/ota/simple_ota_example/CMakeLists.txt
@@ -0,0 +1,14 @@
+# The following four lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/simple_ota_example.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(simple_ota)
+
+# Embed the server root certificate into the final binary
+#
+# (If this was a component, we would set COMPONENT_EMBED_TXTFILES here.)
+target_add_binary_data(simple_ota.elf
+    "../server_certs/ca_cert.pem" TEXT)
diff --git a/examples/wifi/simple_wifi/CMakeLists.txt b/examples/wifi/simple_wifi/CMakeLists.txt
new file mode 100644
index 000000000..57158b16b
--- /dev/null
+++ b/examples/wifi/simple_wifi/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/simple_wifi.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(simple_wifi)
diff --git a/tools/ci/check_examples_cmake_make.sh b/tools/ci/check_examples_cmake_make.sh
new file mode 100755
index 000000000..2f2d84413
--- /dev/null
+++ b/tools/ci/check_examples_cmake_make.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+
+# While we support GNU Make & CMake together, check the same examples are present for both
+
+CMAKE_EXAMPLE_PATHS=$( find ${IDF_PATH}/examples/ -type f -name CMakeLists.txt | grep -v "/components/")
+MAKE_EXAMPLE_PATHS=$( find ${IDF_PATH}/examples/ -type f -name Makefile )
+
+# temporary: ignore ULP examples as no ULP toolchain support
+CMAKE_EXAMPLE_PATHS=$( echo "$CMAKE_EXAMPLE_PATHS" | grep -v "/system/ulp")
+MAKE_EXAMPLE_PATHS=$( echo "$MAKE_EXAMPLE_PATHS" | grep -v "/system/ulp")
+
+CMAKE_EXAMPLE_PATHS="$(/usr/bin/dirname $CMAKE_EXAMPLE_PATHS | sort -n)"
+MAKE_EXAMPLE_PATHS="$(/usr/bin/dirname $MAKE_EXAMPLE_PATHS | sort -n)"
+
+MISMATCH=$(comm -3 <(echo "$MAKE_EXAMPLE_PATHS") <(echo "$CMAKE_EXAMPLE_PATHS"))
+
+if [ -n "$MISMATCH" ]; then
+    echo "Some examples are not in both CMake and GNU Make:"
+    echo "$MISMATCH"
+    exit 1
+fi
+
+echo "Example lists match"
+exit 0
diff --git a/tools/ci/executable-list.txt b/tools/ci/executable-list.txt
index b6b357d5d..71e70c20b 100644
--- a/tools/ci/executable-list.txt
+++ b/tools/ci/executable-list.txt
@@ -49,6 +49,7 @@ tools/unit-test-app/unit_test.py
 tools/windows/eclipse_make.sh
 tools/ci/build_examples_cmake.sh
 tools/ci/test_build_system_cmake.sh
+tools/ci/check_examples_cmake_make.sh
 tools/cmake/convert_to_cmake.py
 tools/cmake/run_cmake_lint.sh
 tools/idf.py

From c921f141281e070beba05a09fe18d43dec446c02 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 31 Aug 2018 11:56:03 +0800
Subject: [PATCH 105/112] cmake: Generate list of components with dependent
 items first, use deterministic ordering

Guarantees that a component's project_include.cmake will be called after its dependent components'
project_include.cmake. Because of cycles in the dependency graph, this is less useful than you'd
think but it gives a strong guarantee for any component which is not part of a cycle.

Also applies deterministic ordering (ordering is initialised as COMPONENT_REQUIRES_COMMON then all
COMPONENTS in alphabetical order, but then the sorting by dependencies is applied.)
---
 docs/en/api-guides/build-system-cmake.rst     | 19 ++++++++--
 tools/cmake/project.cmake                     | 12 +++----
 tools/cmake/scripts/expand_requirements.cmake | 36 +++++++++++++++----
 3 files changed, 51 insertions(+), 16 deletions(-)

diff --git a/docs/en/api-guides/build-system-cmake.rst b/docs/en/api-guides/build-system-cmake.rst
index 7fbf78c3b..d0423c01e 100644
--- a/docs/en/api-guides/build-system-cmake.rst
+++ b/docs/en/api-guides/build-system-cmake.rst
@@ -407,10 +407,21 @@ Requirements in the build system implementation
 -----------------------------------------------
 
 - Very early in the CMake configuration process, the script ``expand_requirements.cmake`` is run. This script does a partial evaluation of all component CMakeLists.txt files and builds a graph of component requirements (this graph may have cycles). The graph is used to generate a file ``component_depends.cmake`` in the build directory.
-- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable).
+- The main CMake process then includes this file and uses it to determine the list of components to include in the build (internal ``BUILD_COMPONENTS`` variable). The ``BUILD_COMPONENTS`` variable is sorted so dependencies are listed first, however as the component dependency graph has cycles this cannot be guaranteed for all components. The order should be deterministic given the same set of components and component dependencies.
+- The value of ``BUILD_COMPONENTS`` is logged by CMake as "Component names: "
 - Configuration is then evaluated for the components included in the build.
 - Each component is included in the build normally and the CMakeLists.txt file is evaluated again to add the component libraries to the build.
 
+Component Dependency Order
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The order of components in the ``BUILD_COMPONENTS`` variable determines other orderings during the build:
+
+- Order that :ref:`project_include.cmake` files are included into the project.
+- Order that the list of header paths is generated for compilation (via ``-I`` argument). (Note that for a given component's source files, only that component's dependency's header paths are passed to the compiler.)
+- Order that component object archives are passed to the linker (note that the build system also passes ``--start-group`` and ``--end-group`` to the linker to allow cycles in linker dependencies, however the basic order is determined by ``BUILD_COMPONENTS``.
+
+
 Build Process Internals
 =======================
 
@@ -434,7 +445,7 @@ The custom ``project()`` function performs the following steps:
 - Sets the `CMAKE_TOOLCHAIN_FILE`_ variable to the ESP-IDF toolchain file with the Xtensa ESP32 toolchain.
 - Declare the actual cmake-level project by calling the `CMake project function <cmake project_>`_.
 - Load the git version. This includes some magic which will automatically re-run CMake if a new revision is checked out in git. See `File Globbing & Incremental Builds`_.
-- Include ``project_include.cmake`` files from any components which have them.
+- Include :ref:`project_include.cmake` files from any components which have them.
 - Add each component to the build. Each component CMakeLists file calls ``register_component``, calls the CMake `add_library <cmake add_library_>`_ function to add a library and then adds source files, compile options, etc.
 - Add the final app executable to the build.
 - Go back and add inter-component dependencies between components (ie adding the public header directories of each component to each other component).
@@ -462,6 +473,8 @@ If you don't want this behaviour, it can be disabled by passing ``--no-warnings`
 Overriding Parts of the Project
 -------------------------------
 
+.. _project_include.cmake:
+
 project_include.cmake
 ^^^^^^^^^^^^^^^^^^^^^
 
@@ -475,6 +488,8 @@ Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cm
 
 Note that ``project_include.cmake`` isn't necessary for the most common component uses - such as adding include directories to the project, or ``LDFLAGS`` to the final linking step. These values can be customised via the ``CMakeLists.txt`` file itself. See `Optional Project Variables`_ for details.
 
+``project_include.cmake`` files are included in the order given in ``BUILD_COMPONENTS`` variable (as logged by CMake). This means that a component's ``project_include.cmake`` file will be included after it's all dependencies' ``project_include.cmake`` files, unless both components are part of a dependency cycle. This is important if a ``project_include.cmake`` file relies on variables set by another component. See also :ref:`above<component-requirements-implementation>`.
+
 Take great care when setting variables or targets in a ``project_include.cmake`` file. As the values are included into the top-level project CMake pass, they can influence or break functionality across all components!
 
 KConfig.projbuild
diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index e914ac1da..bf1ab269b 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -47,15 +47,13 @@ macro(project name)
     # Set global variables used by rest of the build
     idf_set_global_variables()
 
-    # Establish dependencies for components in the build
-    # (this happens before we even generate config...)
-    if(COMPONENTS)
-        # Make sure if an explicit list of COMPONENTS is given, it contains the "common" component requirements
-        # (otherwise, if COMPONENTS is empty then all components will be included in the build.)
-        set(COMPONENTS "${COMPONENTS} ${COMPONENT_REQUIRES_COMMON}")
-    endif()
+    # Sort the components list, as it may be found via filesystem
+    # traversal and therefore in a non-deterministic order
+    list(SORT COMPONENTS)
+
     execute_process(COMMAND "${CMAKE_COMMAND}"
         -D "COMPONENTS=${COMPONENTS}"
+        -D "COMPONENT_REQUIRES_COMMON=${COMPONENT_REQUIRES_COMMON}"
         -D "DEPENDENCIES_FILE=${CMAKE_BINARY_DIR}/component_depends.cmake"
         -D "COMPONENT_DIRS=${COMPONENT_DIRS}"
         -D "BOOTLOADER_BUILD=${BOOTLOADER_BUILD}"
diff --git a/tools/cmake/scripts/expand_requirements.cmake b/tools/cmake/scripts/expand_requirements.cmake
index a825a7647..673357da1 100644
--- a/tools/cmake/scripts/expand_requirements.cmake
+++ b/tools/cmake/scripts/expand_requirements.cmake
@@ -4,6 +4,8 @@
 # Parameters:
 # - COMPONENTS = Space-separated list of initial components to include in the build.
 #   Can be empty, in which case all components are in the build.
+# - COMPONENT_REQUIRES_COMMON = Components to always include in the build, and treated as dependencies
+#   of all other components.
 # - DEPENDENCIES_FILE = Path of generated cmake file which will contain the expanded dependencies for these
 #   components.
 # - COMPONENT_DIRS = List of paths to search for all components.
@@ -13,6 +15,19 @@
 # components required for the build, and the get_component_requirements() function to return each component's
 # recursively expanded requirements.
 #
+# BUILD_COMPONENTS & BUILD_COMPONENT_PATHS will be ordered in a best-effort way so that dependencies are listed first.
+# (Note that IDF supports cyclic dependencies, and dependencies in a cycle have ordering guarantees.)
+#
+# Determinism:
+#
+# Given the the same list of names in COMPONENTS (regardless of order), and an identical value of
+# COMPONENT_REQUIRES_COMMON, and all the same COMPONENT_REQUIRES & COMPONENT_PRIV_REQUIRES values in
+# each component, then the output of BUILD_COMPONENTS should always be in the same
+# order.
+#
+# BUILD_COMPONENT_PATHS will be in the same component order as BUILD_COMPONENTS, even if the
+# actual component paths are different due to different paths.
+#
 # TODO: Error out if a component requirement is missing
 cmake_minimum_required(VERSION 3.5)
 include("${IDF_PATH}/tools/cmake/utilities.cmake")
@@ -26,6 +41,8 @@ if(NOT COMPONENT_DIRS)
 endif()
 spaces2list(COMPONENT_DIRS)
 
+spaces2list(COMPONENT_REQUIRES_COMMON)
+
 function(debug message)
     if(DEBUG)
         message(STATUS "${message}")
@@ -123,10 +140,11 @@ endfunction()
 # also invoking the components to call register_component() above,
 # which will add per-component global properties with dependencies, etc.
 function(expand_component_requirements component)
-    get_property(build_components GLOBAL PROPERTY BUILD_COMPONENTS)
-    if(${component} IN_LIST build_components)
-        return()  # already added this component
+    get_property(seen_components GLOBAL PROPERTY SEEN_COMPONENTS)
+    if(${component} IN_LIST seen_components)
+        return()  # already added, or in process of adding, this component
     endif()
+    set_property(GLOBAL APPEND PROPERTY SEEN_COMPONENTS ${component})
 
     find_component_path("${component}" "${ALL_COMPONENT_PATHS}" component_path)
     debug("Expanding dependencies of ${component} @ ${component_path}")
@@ -142,14 +160,17 @@ function(expand_component_requirements component)
     set(COMPONENT ${component})
     include(${component_path}/CMakeLists.txt)
 
-    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENT_PATHS ${component_path})
-    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENTS ${component})
-
     get_property(requires GLOBAL PROPERTY "${component}_REQUIRES")
     get_property(requires_priv GLOBAL PROPERTY "${component}_PRIV_REQUIRES")
-    foreach(req ${requires} ${requires_priv})
+
+    # Recurse dependencies first, so that they appear first in the list (when possible)
+    foreach(req ${COMPONENT_REQUIRES_COMMON} ${requires} ${requires_priv})
         expand_component_requirements(${req})
     endforeach()
+
+    # Now append this component to the full list (after its dependencies)
+    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENT_PATHS ${component_path})
+    set_property(GLOBAL APPEND PROPERTY BUILD_COMPONENTS ${component})
 endfunction()
 
 
@@ -166,6 +187,7 @@ spaces2list(COMPONENTS)
 debug("ALL_COMPONENT_PATHS ${ALL_COMPONENT_PATHS}")
 debug("ALL_COMPONENTS ${ALL_COMPONENTS}")
 
+set_property(GLOBAL PROPERTY SEEN_COMPONENTS "")  # anti-infinite-recursion
 set_property(GLOBAL PROPERTY BUILD_COMPONENTS "")
 set_property(GLOBAL PROPERTY BUILD_COMPONENT_PATHS "")
 set_property(GLOBAL PROPERTY COMPONENTS_NOT_FOUND "")

From a6282e3e5e3b17619b6ee61b986a0eaaf441939f Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 31 Aug 2018 12:29:38 +0800
Subject: [PATCH 106/112] cmake idf.py: Print flasher file arguments in order
 of file offset

Previously, order was random
---
 tools/idf.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/idf.py b/tools/idf.py
index bb55ff59e..1f017e7fc 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -338,7 +338,8 @@ def print_closing_message(args):
             cmd += flasher_path(flasher_args[key]["file"])
         else:  # flashing the whole project
             cmd = " ".join(flasher_args["write_flash_args"]) + " "
-            flash_items = sorted((o,f) for (o,f) in flasher_args["flash_files"].items() if len(o) > 0)
+            flash_items = sorted(((o,f) for (o,f) in flasher_args["flash_files"].items() if len(o) > 0),
+                                 key = lambda (o,_): int(o, 0))
             for o,f in flash_items:
                 cmd += o + " " + flasher_path(f) + " "
 

From 38c062609088351bae8ccc59cf867c65b011a0d7 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Fri, 31 Aug 2018 12:30:14 +0800
Subject: [PATCH 107/112] cmake app_update: Add "flash blank otadata"
 functionality to cmake

---
 components/app_update/CMakeLists.txt        | 12 +++++++++++-
 components/app_update/project_include.cmake |  8 ++++++++
 components/esptool_py/flash_project_args.in |  4 +++-
 components/esptool_py/flasher_args.json.in  | 13 ++++++++-----
 4 files changed, 30 insertions(+), 7 deletions(-)
 create mode 100644 components/app_update/project_include.cmake

diff --git a/components/app_update/CMakeLists.txt b/components/app_update/CMakeLists.txt
index e1401c685..b69d109b8 100644
--- a/components/app_update/CMakeLists.txt
+++ b/components/app_update/CMakeLists.txt
@@ -1,7 +1,17 @@
 set(COMPONENT_SRCDIRS ".")
 set(COMPONENT_ADD_INCLUDEDIRS "include")
 
-set(COMPONENT_REQUIRES spi_flash)
+set(COMPONENT_REQUIRES spi_flash partition_table)
 set(COMPONENT_PRIV_REQUIRES bootloader_support)
 
 register_component()
+
+# Add custom target for generating empty otadata partition for flashing
+if(${OTADATA_PARTITION_OFFSET})
+    add_custom_command(OUTPUT "${PROJECT_BINARY_DIR}/${BLANK_OTADATA_FILE}"
+        COMMAND ${PYTHON} ${CMAKE_CURRENT_SOURCE_DIR}/gen_empty_partition.py
+        --size ${OTADATA_PARTITION_SIZE} "${PROJECT_BINARY_DIR}/${BLANK_OTADATA_FILE}")
+
+    add_custom_target(blank_ota_data ALL DEPENDS "${PROJECT_BINARY_DIR}/${BLANK_OTADATA_FILE}")
+    add_dependencies(flash blank_ota_data)
+endif()
diff --git a/components/app_update/project_include.cmake b/components/app_update/project_include.cmake
new file mode 100644
index 000000000..70b896f05
--- /dev/null
+++ b/components/app_update/project_include.cmake
@@ -0,0 +1,8 @@
+
+# Set empty otadata partition file for flashing, if OTA data partition in
+# partition table
+# (NB: because of component dependency, we know partition_table
+# project_include.cmake has already been included.)
+if(${OTADATA_PARTITION_OFFSET})
+    set(BLANK_OTADATA_FILE "ota_data_initial.bin")
+endif()
diff --git a/components/esptool_py/flash_project_args.in b/components/esptool_py/flash_project_args.in
index d3eb6f582..c09bc08fb 100644
--- a/components/esptool_py/flash_project_args.in
+++ b/components/esptool_py/flash_project_args.in
@@ -3,5 +3,7 @@
 --flash_freq ${ESPFLASHFREQ}
 0x1000 bootloader/bootloader.bin
 ${PARTITION_TABLE_OFFSET} partition_table/partition-table.bin
-${APP_PARTITION_OFFSET} ${PROJECT_NAME}.bin
 ${PHY_PARTITION_OFFSET} ${PHY_PARTITION_BIN_FILE}
+${OTADATA_PARTITION_OFFSET} ${BLANK_OTADATA_FILE}
+${APP_PARTITION_OFFSET} ${PROJECT_NAME}.bin
+
diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
index 4ec3a8c24..c6b9d2c8e 100644
--- a/components/esptool_py/flasher_args.json.in
+++ b/components/esptool_py/flasher_args.json.in
@@ -5,13 +5,16 @@
     "flash_files" : {
         "0x1000" : "bootloader/bootloader.bin",
         "${PARTITION_TABLE_OFFSET}" : "partition_table/partition-table.bin",
-        "${APP_PARTITION_OFFSET}" : "${PROJECT_NAME}.bin",
-        "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}"
+        "${PHY_PARTITION_OFFSET}" : "${PHY_PARTITION_BIN_FILE}",
+        "${OTADATA_PARTITION_OFFSET}" : "${BLANK_OTADATA_FILE}",
+        "${APP_PARTITION_OFFSET}" : "${PROJECT_NAME}.bin"
     },
     "bootloader" :      { "offset" : "0x1000",
                           "file" : "bootloader/bootloader.bin" },
-    "app" :             { "offset" : "${APP_PARTITION_OFFSET}",
-                          "file" : "${PROJECT_NAME}.bin" },
     "partition_table" : { "offset" : "${PARTITION_TABLE_OFFSET}",
-                          "file" : "partition_table/partition-table.bin" }
+                          "file" : "partition_table/partition-table.bin" },
+    "otadata" : { "offset" : "${OTADATA_PARTITION_OFFSET}",
+                  "file" : "${BLANK_OTADATA_FILE}" },
+    "app" :             { "offset" : "${APP_PARTITION.py_OFFSET}",
+                          "file" : "${PROJECT_NAME}.bin" }
 }

From 6fa52ca8fe053118d3cc44dc9202ed88da99685d Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Mon, 3 Sep 2018 18:24:17 +0800
Subject: [PATCH 108/112] cmake: Call check_python_dependencies.py from idf.py
 & cmake

---
 tools/cmake/project.cmake |  9 +++++++++
 tools/idf.py              | 16 +++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/tools/cmake/project.cmake b/tools/cmake/project.cmake
index bf1ab269b..8784a9e9b 100644
--- a/tools/cmake/project.cmake
+++ b/tools/cmake/project.cmake
@@ -29,6 +29,15 @@ include(idf_functions)
 
 set_default(PYTHON "python")
 
+if(NOT PYTHON_DEPS_CHECKED AND NOT BOOTLOADER_BUILD)
+    message(STATUS "Checking Python dependencies...")
+    execute_process(COMMAND "${PYTHON}" "${IDF_PATH}/tools/check_python_dependencies.py"
+        RESULT_VARIABLE result)
+    if(NOT result EQUAL 0)
+        message(FATAL_ERROR "Some Python dependencies must be installed. Check above message for details.")
+    endif()
+endif()
+
 # project
 #
 # This macro wraps the cmake 'project' command to add
diff --git a/tools/idf.py b/tools/idf.py
index 1f017e7fc..2f552fa5d 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -21,6 +21,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+
+# Note: we don't check for Python build-time dependencies until
+# check_environment() function below. If possible, avoid importing
+# any external libraries here - put in external script, or import in
+# their specific function instead.
 import sys
 import argparse
 import os
@@ -98,6 +103,15 @@ def check_environment():
         print("Setting IDF_PATH environment variable: %s" % detected_idf_path)
         os.environ["IDF_PATH"] = detected_idf_path
 
+    # check Python dependencies
+    print("Checking Python dependencies...")
+    try:
+        subprocess.check_call([ os.environ["PYTHON"],
+                                os.path.join(os.environ["IDF_PATH"], "tools", "check_python_dependencies.py")],
+                              env=os.environ)
+    except subprocess.CalledProcessError:
+        raise SystemExit(1)
+
 def executable_exists(args):
     try:
         subprocess.check_output(args)
@@ -143,7 +157,7 @@ def _ensure_build_directory(args, always_run_cmake=False):
         if args.generator is None:
             args.generator = detect_cmake_generator()
         try:
-            cmake_args = ["cmake", "-G", args.generator]
+            cmake_args = ["cmake", "-G", args.generator, "-DPYTHON_DEPS_CHECKED=1"]
             if not args.no_warnings:
                 cmake_args += [ "--warn-uninitialized" ]
             if args.no_ccache:

From 0bc5dcc2c27be7e0bf077b64ac780e42a03de328 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Wed, 5 Sep 2018 17:27:19 +0800
Subject: [PATCH 109/112] cmake: Post-merge fixups

---
 components/esptool_py/flasher_args.json.in      | 2 +-
 docs/conf_common.py                             | 6 ++++--
 examples/get-started/hello_world/partitions.csv | 5 -----
 3 files changed, 5 insertions(+), 8 deletions(-)
 delete mode 100644 examples/get-started/hello_world/partitions.csv

diff --git a/components/esptool_py/flasher_args.json.in b/components/esptool_py/flasher_args.json.in
index c6b9d2c8e..6a4128f13 100644
--- a/components/esptool_py/flasher_args.json.in
+++ b/components/esptool_py/flasher_args.json.in
@@ -15,6 +15,6 @@
                           "file" : "partition_table/partition-table.bin" },
     "otadata" : { "offset" : "${OTADATA_PARTITION_OFFSET}",
                   "file" : "${BLANK_OTADATA_FILE}" },
-    "app" :             { "offset" : "${APP_PARTITION.py_OFFSET}",
+    "app" :             { "offset" : "${APP_PARTITION_OFFSET}",
                           "file" : "${PROJECT_NAME}.bin" }
 }
diff --git a/docs/conf_common.py b/docs/conf_common.py
index 25f048adf..2a803664d 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -53,14 +53,16 @@ kconfig_inc_path = '{}/inc/kconfig.inc'.format(builddir)
 temp_sdkconfig_path = '{}/sdkconfig.tmp'.format(builddir)
 kconfigs = subprocess.check_output(["find", "../../components", "-name", "Kconfig"]).decode()
 kconfig_projbuilds = subprocess.check_output(["find", "../../components", "-name", "Kconfig.projbuild"]).decode()
-call_with_python(" ".join(
+confgen_args = [sys.executable,
                 "../../tools/kconfig_new/confgen.py",
                 "--kconfig", "../../Kconfig",
                 "--config", temp_sdkconfig_path,
                 "--create-config-if-missing",
                 "--env", "COMPONENT_KCONFIGS={}".format(kconfigs),
                 "--env", "COMPONENT_KCONFIGS_PROJBUILD={}".format(kconfig_projbuilds),
-                "--output", "docs", kconfig_inc_path + '.in'))
+                "--output", "docs", kconfig_inc_path + '.in'
+]
+subprocess.check_call(confgen_args)
 copy_if_modified(kconfig_inc_path + '.in', kconfig_inc_path)
 
 # Generate 'esp_err_defs.inc' file with ESP_ERR_ error code definitions
diff --git a/examples/get-started/hello_world/partitions.csv b/examples/get-started/hello_world/partitions.csv
deleted file mode 100644
index 22cf97bac..000000000
--- a/examples/get-started/hello_world/partitions.csv
+++ /dev/null
@@ -1,5 +0,0 @@
-# Name,   Type, SubType, Offset,  Size, Flags
-# Note: if you change the phy_init or app partition offset, make sure to change the offset in Kconfig.projbuild
-nvs,      data, nvs,     ,        0x6000,
-phy_init, data, phy,     ,        0x1000,
-factory,  app,  factory, ,        1M,

From c1b8949a1e9a188b828af6276a0573bb7bc3ef42 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 6 Sep 2018 16:20:13 +0800
Subject: [PATCH 110/112] cmake: Add CMakeLists.txt file for WiFi station
 example

---
 examples/wifi/getting_started/station/CMakeLists.txt | 8 ++++++++
 1 file changed, 8 insertions(+)
 create mode 100644 examples/wifi/getting_started/station/CMakeLists.txt

diff --git a/examples/wifi/getting_started/station/CMakeLists.txt b/examples/wifi/getting_started/station/CMakeLists.txt
new file mode 100644
index 000000000..482582136
--- /dev/null
+++ b/examples/wifi/getting_started/station/CMakeLists.txt
@@ -0,0 +1,8 @@
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+set(MAIN_SRCS main/station_example_main.c)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(wifi_station)

From deb46b415f43ced3752eac8acba53eaa7234aec2 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 6 Sep 2018 20:23:20 +0800
Subject: [PATCH 111/112] lwip: Re-add CONFIG_PPP_SUPPORT check, remove
 redundant CFLAGS

---
 components/lwip/component.mk | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/components/lwip/component.mk b/components/lwip/component.mk
index 914ab6577..d79cbd36c 100644
--- a/components/lwip/component.mk
+++ b/components/lwip/component.mk
@@ -18,15 +18,13 @@ COMPONENT_SRCDIRS := \
 	lwip/src/core/ipv4 \
 	lwip/src/core/ipv6 \
 	lwip/src/netif \
-	lwip/src/netif/ppp \
 	port/esp32 \
 	port/esp32/freertos \
 	port/esp32/netif \
-	port/esp32/debug 
+	port/esp32/debug
+
+ifdef CONFIG_PPP_SUPPORT
+    COMPONENT_SRCDIRS += lwip/src/netif/ppp lwip/src/netif/ppp/polarssl
+endif
 
 CFLAGS += -Wno-address  # lots of LWIP source files evaluate macros that check address of stack variables
-
-api/tcpip.o apps/dhcpserver.o: CFLAGS += -Wno-unused-variable
-apps/dhcpserver.o core/pbuf.o core/tcp_in.o: CFLAGS += -Wno-unused-but-set-variable
-netif/ppp/pppos.o: CFLAGS += -Wno-type-limits
-

From 36bc73e5a6b5b016b93fc0949977f58b863a2de5 Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Thu, 6 Sep 2018 20:32:49 +0800
Subject: [PATCH 112/112] idf.py: Choose a default serial port for all targets
 if '-p' is not given

---
 tools/idf.py | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/tools/idf.py b/tools/idf.py
index 2f552fa5d..ce46b83b3 100755
--- a/tools/idf.py
+++ b/tools/idf.py
@@ -35,6 +35,7 @@ import multiprocessing
 import re
 import shutil
 import json
+import serial.tools.list_ports
 
 class FatalError(RuntimeError):
     """
@@ -236,9 +237,10 @@ def build_target(target_name, args):
 
 def _get_esptool_args(args):
     esptool_path = os.path.join(os.environ["IDF_PATH"], "components/esptool_py/esptool/esptool.py")
+    if args.port is None:
+        args.port = get_default_serial_port()
     result = [ PYTHON, esptool_path ]
-    if args.port is not None:
-        result += [ "-p", args.port ]
+    result += [ "-p", args.port ]
     result += [ "-b", str(args.baud) ]
     return result
 
@@ -267,6 +269,8 @@ def monitor(action, args):
     """
     Run idf_monitor.py to watch build output
     """
+    if args.port is None:
+        args.port = get_default_serial_port()
     desc_path = os.path.join(args.build_dir, "project_description.json")
     if not os.path.exists(desc_path):
         _ensure_build_directory(args)
@@ -409,6 +413,21 @@ def get_commandline_options():
             result.append(a)
     return result
 
+def get_default_serial_port():
+    """ Return a default serial port. esptool can do this (smarter), but it can create
+    inconsistencies where esptool.py uses one port and idf_monitor uses another.
+
+    Same logic as esptool.py search order, reverse sort by name and choose the first port.
+    """
+    ports = list(reversed(sorted(
+        p.device for p in serial.tools.list_ports.comports() )))
+    try:
+        print ("Choosing default port %s (use '-p PORT' option to set a specific serial port)" % ports[0])
+        return ports[0]
+    except IndexError:
+        raise RuntimeError("No serial ports found. Connect a device, or use '-p PORT' option to set a specific port.")
+
+
 def main():
     if sys.version_info[0] != 2 or sys.version_info[1] != 7:
         raise FatalError("ESP-IDF currently only supports Python 2.7, and this is Python %d.%d.%d. Search for 'Setting the Python Interpreter' in the ESP-IDF docs for some tips to handle this." % sys.version_info[:3])