Merge branch 'feature/cmake' into 'master'

Merge experimental CMake support to master

See merge request idf/esp-idf!3024

.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

.gitignore

@@ -57,4 +57,11 @@ examples/protocols/aws_iot/*/main/certs/*.pem.*
 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
+
 test_multi_heap_host
+

.gitlab-ci.yml

@@ -202,6 +202,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
@@ -260,6 +266,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
+
 .host_test_template: &host_test_template
   stage: host_test
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG
@@ -373,6 +385,12 @@ test_multi_heap_on_host:
     - cd components/heap/test_multi_heap_host
     - ./test_all_configs.sh
 
+test_confserver:
+  <<: *host_test_template
+  script:
+    - cd tools/kconfig_new/test
+    - ./test_confserver.py
+
 test_build_system:
   <<: *host_test_template
   script:
@@ -382,6 +400,15 @@ test_build_system:
     - cd test_build_system
     - ${IDF_PATH}/tools/ci/test_build_system.sh
 
+test_build_system_cmake:
+  <<: *host_test_template
+  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_idf_monitor:
   <<: *host_test_template
   artifacts:
@@ -530,6 +557,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: check
   image: $CI_DOCKER_REGISTRY/esp32-ci-env$BOT_DOCKER_IMAGE_TAG

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
@@ -15,11 +18,15 @@ 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
         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"
@@ -35,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"

Kconfig.compiler

@@ -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

README.md

@@ -49,7 +49,7 @@ NOTE: The `-j4` option causes `make` to run 4 parallel jobs. This is much faster
 
 ## 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 -j4 flash`
 
@@ -88,6 +88,7 @@ Multiple make functions can be combined into one. For example: to build the app
 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.

components/app_trace/CMakeLists.txt

@@ -0,0 +1,24 @@
+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()
+
+set(COMPONENT_REQUIRES)
+set(COMPONENT_PRIV_REQUIRES xtensa-debug-module)
+
+register_component()
+
+# disable --coverage for this component, as it is used as transport
+# for gcov
+component_compile_options("-fno-profile-arcs" "-fno-test-coverage")

components/app_update/CMakeLists.txt

@@ -0,0 +1,17 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+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()

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"

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"

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()

components/asio/CMakeLists.txt

@@ -0,0 +1,8 @@
+set(COMPONENT_ADD_INCLUDEDIRS asio/asio/include port/include)
+set(COMPONENT_SRCDIRS asio/asio/src)
+
+set(COMPONENT_SRCEXCLUDE asio/asio/src/asio_ssl.cpp)
+
+set(COMPONENT_REQUIRES lwip)
+
+register_component()

components/aws_iot/CMakeLists.txt

@@ -0,0 +1,11 @@
+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_REQUIRES "mbedtls")
+set(COMPONENT_PRIV_REQUIRES "jsmn")
+
+register_component()

components/bootloader/CMakeLists.txt

@@ -0,0 +1,7 @@
+# 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
+
+

components/bootloader/project_include.cmake

@@ -0,0 +1,33 @@
+if(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_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"
+    )
+
+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})

components/bootloader/subproject/CMakeLists.txt

@@ -0,0 +1,30 @@
+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.")
+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 partition_table soc bootloader_support log spi_flash micro-ecc soc)
+set(BOOTLOADER_BUILD 1)
+add_definitions(-DBOOTLOADER_BUILD=1)
+
+set(COMPONENT_REQUIRES_COMMON log esp32 soc)
+
+set(MAIN_SRCS main/bootloader_start.c)
+
+include("${IDF_PATH}/tools/cmake/project.cmake")
+project(bootloader)
+
+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)

components/bootloader/subproject/main/esp32.bootloader.ld

@@ -41,19 +41,19 @@ SECTIONS
      *(.iram1 .iram1.*) /* catch stray IRAM_ATTR */
     *liblog.a:(.literal .text .literal.* .text.*)
     *libgcc.a:(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:bootloader_common.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:bootloader_common.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:bootloader_flash.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:bootloader_flash.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:bootloader_random.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:bootloader_random.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:bootloader_utility.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:bootloader_utility.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:bootloader_sha.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:bootloader_sha.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:efuse.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:efuse.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:esp_image_format.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:esp_image_format.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:flash_encrypt.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:flash_encrypt.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:flash_partitions.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:flash_partitions.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:secure_boot.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:secure_boot.*(.literal .text .literal.* .text.*)
-    *libbootloader_support.a:secure_boot_signatures.o(.literal .text .literal.* .text.*)
+    *libbootloader_support.a:secure_boot_signatures.*(.literal .text .literal.* .text.*)
-    *libmicro-ecc.a:*.o(.literal .text .literal.* .text.*)
+    *libmicro-ecc.a:*.*(.literal .text .literal.* .text.*)
-    *libspi_flash.a:*.o(.literal .text .literal.* .text.*)
+    *libspi_flash.a:*.*(.literal .text .literal.* .text.*)
     *(.fini.literal)
     *(.fini)
     *(.gnu.version)
@@ -125,13 +125,13 @@ SECTIONS
     . = (. + 3) & ~ 3;
     /*  C++ constructor and destructor tables, properly ordered:  */
     __init_array_start = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.ctors))
+    KEEP (*crtbegin.*(.ctors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .ctors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .ctors))
     KEEP (*(SORT(.ctors.*)))
     KEEP (*(.ctors))
     __init_array_end = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.dtors))
+    KEEP (*crtbegin.*(.dtors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .dtors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .dtors))
     KEEP (*(SORT(.dtors.*)))
     KEEP (*(.dtors))
     /*  C++ exception handlers table:  */

components/bootloader_support/CMakeLists.txt

@@ -0,0 +1,14 @@
+set(COMPONENT_SRCDIRS "src")
+
+if(${BOOTLOADER_BUILD})
+    set(COMPONENT_ADD_INCLUDEDIRS "include include_bootloader")
+    set(COMPONENT_REQUIRES)
+    set(COMPONENT_PRIV_REQUIRES spi_flash micro-ecc)
+else()
+    set(COMPONENT_ADD_INCLUDEDIRS "include")
+    set(COMPONENT_PRIV_INCLUDEDIRS "include_bootloader")
+    set(COMPONENT_REQUIRES)
+    set(COMPONENT_PRIV_REQUIRES spi_flash mbedtls micro-ecc)
+endif()
+
+register_component()

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"
 
 /**

components/bt/CMakeLists.txt

@@ -0,0 +1,92 @@
+if(CONFIG_BT_ENABLED)
+
+    set(COMPONENT_SRCDIRS .)
+    set(COMPONENT_ADD_INCLUDEDIRS include)
+
+    if(CONFIG_BLUEDROID_ENABLED)
+
+        list(APPEND COMPONENT_PRIV_INCLUDEDIRS
+            bluedroid/bta/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/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()
+
+# requirements can't depend on config
+set(COMPONENT_PRIV_REQUIRES nvs_flash)
+
+register_component()
+
+if(CONFIG_BT_ENABLED)
+    target_link_libraries(bt "-L${CMAKE_CURRENT_LIST_DIR}/lib")
+    target_link_libraries(bt btdm_app)
+endif()

components/bt/Kconfig

@@ -169,7 +169,7 @@ endchoice
 endmenu
 
 config BLE_SCAN_DUPLICATE
-    bool "BLE Scan Duplicate Options "
+    bool "BLE Scan Duplicate Options"
     depends on (BTDM_CONTROLLER_MODE_BTDM || BTDM_CONTROLLER_MODE_BLE_ONLY)
     default y
     help

components/coap/CMakeLists.txt

@@ -0,0 +1,41 @@
+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_REQUIRES lwip)
+
+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)
+
+set_source_files_properties(
+    libcoap/src/debug.c
+    libcoap/src/pdu.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-write-strings)
+
+# Temporary suppress "fallthrough" warnings until they are fixed in libcoap repo
+set_source_files_properties(
+    libcoap/src/option.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-implicit-fallthrough)

components/console/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(COMPONENT_ADD_INCLUDEDIRS .)
+set(COMPONENT_SRCDIRS linenoise argtable3 .)
+
+set(COMPONENT_REQUIRES)
+
+register_component()
+

components/cxx/CMakeLists.txt

@@ -0,0 +1,11 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_REQUIRES)
+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()

components/driver/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS "include/driver")
+
+set(COMPONENT_REQUIRES)
+
+register_component()

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()

components/esp32/CMakeLists.txt

@@ -0,0 +1,98 @@
+if(BOOTLOADER_BUILD)
+    # For bootloader, all we need from esp32 is headers
+    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
+    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
+
+    set(COMPONENT_SRCDIRS ". hwcrypto")
+    set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+    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 smartconfig_ack spi_flash vfs wpa_supplicant xtensa-debug-module)
+
+    register_component()
+
+    target_link_libraries(esp32 "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
+    if(NOT CONFIG_NO_BLOBS)
+        target_link_libraries(esp32 coexist core espnow mesh net80211 phy pp rtc smartconfig wpa2 wpa wps)
+    endif()
+    target_linker_script(esp32 "${CMAKE_CURRENT_BINARY_DIR}/esp32_out.ld")
+
+    target_linker_script(esp32
+        "ld/esp32.common.ld"
+        "ld/esp32.rom.ld"
+        "ld/esp32.peripherals.ld"
+        "ld/esp32.rom.libgcc.ld"
+        )
+
+    if(CONFIG_SPIRAM_CACHE_WORKAROUND)
+        add_compile_options(-mfix-esp32-psram-cache-issue)
+    else()
+        target_linker_script(esp32 "ld/esp32.rom.spiram_incompatible_fns.ld")
+    endif()
+
+    if(CONFIG_NEWLIB_NANO_FORMAT)
+        target_linker_script(esp32 "ld/esp32.rom.nanofmt.ld")
+    endif()
+
+    if(NOT CONFIG_SPI_FLASH_ROM_DRIVER_PATCH)
+        target_linker_script(esp32 "ld/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")
+
+    #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 ${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)
+    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
+        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()

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*.*(.bss .bss.*)
-    *rtc_wake_stub*.o(COMMON)
+    *rtc_wake_stub*.*(COMMON)
     *(.rtc.bss)
     _rtc_bss_end = ABSOLUTE(.);
   } > rtc_slow_seg
@@ -95,18 +95,18 @@ 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.*(.literal .text .literal.* .text.*)
-    *libheap.a:multi_heap_poisoning.o(.literal .text .literal.* .text.*)
+    *libheap.a:multi_heap_poisoning.*(.literal .text .literal.* .text.*)
-    *libesp32.a:panic.o(.literal .text .literal.* .text.*)
+    *libesp32.a:panic.*(.literal .text .literal.* .text.*)
-    *libesp32.a:core_dump.o(.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:rtc_*.o(.literal .text .literal.* .text.*)
+    *libsoc.a:rtc_*.*(.literal .text .literal.* .text.*)
-    *libsoc.a:cpu_util.o(.literal .text .literal.* .text.*)
+    *libsoc.a:cpu_util.*(.literal .text .literal.* .text.*)
     *libhal.a:(.literal .text .literal.* .text.*)
-    *libgcc.a:lib2funcs.o(.literal .text .literal.* .text.*)
+    *libgcc.a:lib2funcs.*(.literal .text .literal.* .text.*)
-    *libspi_flash.a:spi_flash_rom_patch.o(.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(.);
@@ -136,13 +136,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.*(.rodata .rodata.*)
-    *libheap.a:multi_heap_poisoning.o(.rodata .rodata.*)
+    *libheap.a:multi_heap_poisoning.*(.rodata .rodata.*)
     INCLUDE esp32.spiram.rom-functions-dram.ld
     _data_end = ABSOLUTE(.);
     . = ALIGN(4);
@@ -214,13 +214,13 @@ SECTIONS
     . = (. + 7) & ~ 3;
     /*  C++ constructor and destructor tables, properly ordered:  */
     __init_array_start = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.ctors))
+    KEEP (*crtbegin.*(.ctors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .ctors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .ctors))
     KEEP (*(SORT(.ctors.*)))
     KEEP (*(.ctors))
     __init_array_end = ABSOLUTE(.);
-    KEEP (*crtbegin.o(.dtors))
+    KEEP (*crtbegin.*(.dtors))
-    KEEP (*(EXCLUDE_FILE (*crtend.o) .dtors))
+    KEEP (*(EXCLUDE_FILE (*crtend.*) .dtors))
     KEEP (*(SORT(.dtors.*)))
     KEEP (*(.dtors))
     /*  C++ exception handlers table:  */

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"
 
@@ -143,3 +144,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 */
+

components/esp_adc_cal/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES)
+
+register_component()

components/esp_http_client/CMakeLists.txt

@@ -0,0 +1,8 @@
+set(COMPONENT_SRCDIRS "." "lib")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS "lib/include")
+
+set(COMPONENT_REQUIRES "nghttp")
+set(COMPONENT_PRIV_REQUIRES "mbedtls" "lwip" "esp-tls")
+
+register_component()

components/esp_https_ota/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_SRCDIRS "src")
+
+set(COMPONENT_REQUIRES esp_http_client)
+set(COMPONENT_PRIV_REQUIRES log app_update)
+
+register_component()

components/esptool_py/CMakeLists.txt

@@ -0,0 +1,14 @@
+register_config_only_component()
+
+# Generate pre-canned flasher args files suitable for passing to esptool.py
+foreach(part project app bootloader partition_table)
+    configure_file(
+        "${CMAKE_CURRENT_LIST_DIR}/flash_${part}_args.in"
+        "${CMAKE_BINARY_DIR}/flash_${part}_args"
+        )
+endforeach()
+
+configure_file(
+    "${CMAKE_CURRENT_LIST_DIR}/flasher_args.json.in"
+    "${CMAKE_BINARY_DIR}/flasher_args.json"
+    )

components/esptool_py/Kconfig.projbuild

@@ -2,18 +2,24 @@ 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
         environment variable.
 
+        This value is ignored when using the CMake-based build system or idf.py.
+
 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
         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"
 config ESPTOOLPY_BAUD_230400B
@@ -32,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
@@ -40,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

components/esptool_py/flash_app_args.in

@@ -0,0 +1 @@
+${APP_PARTITION_OFFSET} ${PROJECT_NAME}.bin

components/esptool_py/flash_bootloader_args.in

@@ -0,0 +1,4 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
+0x1000 bootloader/bootloader.bin

components/esptool_py/flash_partition_table_args.in

@@ -0,0 +1 @@
+${PARTITION_TABLE_OFFSET} partition_table/partition-table.bin

components/esptool_py/flash_project_args.in

@@ -0,0 +1,9 @@
+--flash_mode ${ESPFLASHMODE}
+--flash_size ${ESPFLASHSIZE}
+--flash_freq ${ESPFLASHFREQ}
+0x1000 bootloader/bootloader.bin
+${PARTITION_TABLE_OFFSET} partition_table/partition-table.bin
+${PHY_PARTITION_OFFSET} ${PHY_PARTITION_BIN_FILE}
+${OTADATA_PARTITION_OFFSET} ${BLANK_OTADATA_FILE}
+${APP_PARTITION_OFFSET} ${PROJECT_NAME}.bin
+

components/esptool_py/flasher_args.json.in

@@ -0,0 +1,20 @@
+{
+    "write_flash_args" : [ "--flash_mode", "${ESPFLASHMODE}",
+                           "--flash_size", "${ESPFLASHSIZE}",
+                           "--flash_freq", "${ESPFLASHFREQ}" ],
+    "flash_files" : {
+        "0x1000" : "bootloader/bootloader.bin",
+        "${PARTITION_TABLE_OFFSET}" : "partition_table/partition-table.bin",
+        "${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" },
+    "partition_table" : { "offset" : "${PARTITION_TABLE_OFFSET}",
+                          "file" : "partition_table/partition-table.bin" },
+    "otadata" : { "offset" : "${OTADATA_PARTITION_OFFSET}",
+                  "file" : "${BLANK_OTADATA_FILE}" },
+    "app" :             { "offset" : "${APP_PARTITION_OFFSET}",
+                          "file" : "${PROJECT_NAME}.bin" }
+}

components/esptool_py/project_include.cmake

@@ -0,0 +1,54 @@
+# 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(ESPFLASHMODE ${CONFIG_ESPTOOLPY_FLASHMODE})
+set(ESPFLASHFREQ ${CONFIG_ESPTOOLPY_FLASHFREQ})
+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}
+    )
+
+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 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 '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(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}
+        )
+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")

components/ethernet/CMakeLists.txt

@@ -0,0 +1,7 @@
+set(COMPONENT_SRCDIRS . eth_phy)
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES)
+set(COMPONENT_PRIV_REQUIRES tcpip_adapter)
+
+register_component()

components/ethernet/emac_main.c

@@ -292,8 +292,8 @@ static void emac_set_user_config_data(eth_config_t *config)
 #if DMA_RX_BUF_NUM > 9
     emac_config.emac_flow_ctrl_enable = config->flow_ctrl_enable;
 #else
-    if (config->flow_ctrl_enable == true) {
+    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, "Can only configure flow_ctrl_enable==true if DMA_RX_BUF_NUM in menuconfig is >9. Disabling flow control.");
     }
     emac_config.emac_flow_ctrl_enable = false;
 #endif

components/expat/CMakeLists.txt

@@ -0,0 +1,12 @@
+set(COMPONENT_ADD_INCLUDEDIRS expat/expat/lib port/include)
+set(COMPONENT_SRCDIRS expat/expat/lib)
+
+set(COMPONENT_REQUIRES)
+
+register_component()
+
+component_compile_definitions(HAVE_EXPAT_CONFIG_H)
+component_compile_definitions(HAVE_GETRANDOM)
+
+# Temporary suppress "fallthrough" warnings until they are fixed in expat repo
+component_compile_options(-Wno-implicit-fallthrough)

components/fatfs/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS src)
+set(COMPONENT_ADD_INCLUDEDIRS src)
+
+set(COMPONENT_REQUIRES wear_levelling sdmmc)
+
+register_component()

components/freertos/CMakeLists.txt

@@ -0,0 +1,18 @@
+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")
+
+set_source_files_properties(
+    tasks.c
+    event_groups.c
+    timers.c
+    queue.c
+    ringbuf.c
+    PROPERTIES COMPILE_DEFINITIONS
+    _ESP_FREERTOS_INTERNAL
+    )

components/heap/CMakeLists.txt

@@ -0,0 +1,29 @@
+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()
+
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES "")
+
+register_component()
+
+if(CONFIG_HEAP_TRACING)
+    set(WRAP_FUNCTIONS
+        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}")
+    endforeach()
+
+endif()

components/http_server/CMakeLists.txt

@@ -0,0 +1,8 @@
+set(COMPONENT_ADD_INCLUDEDIRS include)
+set(COMPONENT_PRIV_INCLUDEDIRS src/port/esp32 src/util)
+set(COMPONENT_SRCDIRS src src/util)
+
+set(COMPONENT_REQUIRES nghttp)  # for http_parser.h
+set(COMPONENT_PRIV_REQUIRES lwip)
+
+register_component()

components/idf_test/CMakeLists.txt

@@ -0,0 +1,3 @@
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES)
+register_component()

components/jsmn/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS "src")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES "")
+
+register_component()

components/json/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS cJSON)
+set(COMPONENT_ADD_INCLUDEDIRS cJSON)
+
+set(COMPONENT_REQUIRES "")
+
+register_component()

components/libsodium/CMakeLists.txt

@@ -0,0 +1,107 @@
+set(SRC libsodium/src/libsodium)
+
+set(COMPONENT_REQUIRES "mbedtls")
+
+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()
+
+component_compile_definitions(
+    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
+    )
+set_source_files_properties(
+    ${SRC}/sodium/utils.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-unused-variable
+    )
+
+# Temporary suppress "fallthrough" warnings until they are fixed in libsodium repo
+set_source_files_properties(
+    ${SRC}/crypto_shorthash/siphash24/ref/shorthash_siphashx24_ref.c
+    ${SRC}/crypto_shorthash/siphash24/ref/shorthash_siphash24_ref.c
+    PROPERTIES COMPILE_FLAGS
+    -Wno-implicit-fallthrough)

components/log/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES)
+register_component()

components/lwip/CMakeLists.txt

@@ -0,0 +1,37 @@
+set(COMPONENT_ADD_INCLUDEDIRS
+    include/apps
+    lwip/src/include
+    port/esp32/include
+    port/esp32/include/arch
+    )
+
+set(COMPONENT_SRCDIRS
+    apps/dhcpserver
+	apps/ping
+	lwip/src/api
+	lwip/src/apps/sntp
+	lwip/src/core
+	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
+    )
+
+if(CONFIG_PPP_SUPPORT)
+    list(APPEND COMPONENT_SRCDIRS
+        lwip/src/netif/ppp
+        lwip/src/netif/ppp/polarssl
+        )
+endif()
+
+set(COMPONENT_REQUIRES vfs)
+set(COMPONENT_PRIV_REQUIRES ethernet tcpip_adapter)
+
+register_component()
+
+# lots of LWIP source files evaluate macros that check address of stack variables
+component_compile_options(-Wno-address)

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
 
+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
-

components/mbedtls/CMakeLists.txt

@@ -0,0 +1,12 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include mbedtls/include)
+set(COMPONENT_SRCDIRS mbedtls/library port)
+
+set(COMPONENT_SRCEXCLUDE mbedtls/library/net_sockets.c)
+
+set(COMPONENT_REQUIRES lwip)
+
+register_component()
+
+target_compile_definitions(mbedtls PUBLIC
+    -DMBEDTLS_CONFIG_FILE="mbedtls/esp_config.h"
+)

components/mdns/CMakeLists.txt

@@ -0,0 +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()
+

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_REQUIRES)
+
+register_component()

components/newlib/CMakeLists.txt

@@ -0,0 +1,23 @@
+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)
+else()
+
+    if(CONFIG_NEWLIB_NANO_FORMAT)
+        set(LIBC c_nano)
+    else()
+        set(LIBC c)
+    endif()
+
+    set(LIBM m)
+endif()
+
+set(COMPONENT_REQUIRES vfs)  # for sys/ioctl.h
+
+register_component()
+
+target_link_libraries(newlib "-L ${CMAKE_CURRENT_SOURCE_DIR}/lib")
+target_link_libraries(newlib ${LIBC} ${LIBM})

components/nghttp/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(COMPONENT_ADD_INCLUDEDIRS port/include nghttp2/lib/includes)
+set(COMPONENT_SRCDIRS nghttp2/lib port)
+
+register_component()

components/nvs_flash/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS src)
+set(COMPONENT_ADD_INCLUDEDIRS include)
+
+set(COMPONENT_REQUIRES spi_flash)
+
+register_component()

components/openssl/CMakeLists.txt

@@ -0,0 +1,7 @@
+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()

components/partition_table/CMakeLists.txt

@@ -0,0 +1,70 @@
+register_config_only_component()
+
+if(NOT BOOTLOADER_BUILD)
+
+set(partition_csv "${PARTITION_CSV_PATH}")
+
+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")
+else()
+    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)
+    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 --offset ${PARTITION_TABLE_OFFSET} ${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_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()
+
+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
+set_property(GLOBAL APPEND_STRING PROPERTY
+    ESPTOOL_WRITE_FLASH_ARGS
+    "${PARTITION_TABLE_OFFSET} ${final_partition_bin} ")
+
+endif()

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:

components/partition_table/project_include.cmake

@@ -0,0 +1,58 @@
+if(NOT BOOTLOADER_BUILD)
+
+set(PARTITION_TABLE_OFFSET ${CONFIG_PARTITION_TABLE_OFFSET})
+
+# Set PARTITION_CSV_PATH to the configured partition CSV file
+# absolute path
+if(CONFIG_PARTITION_TABLE_CUSTOM)
+    # Custom filename expands any path relative to the project
+    get_filename_component(PARTITION_CSV_PATH "${CONFIG_PARTITION_TABLE_FILENAME}" ABSOLUTE BASE_DIR "${PROJECT_PATH}")
+
+    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
+    get_filename_component(PARTITION_CSV_PATH "${COMPONENT_PATH}/${CONFIG_PARTITION_TABLE_FILENAME}" ABSOLUTE)
+
+    if(NOT EXISTS "${PARTITION_CSV_PATH}")
+        message(FATAL_ERROR "Internal error, built-in ${PARTITION_CSV_PATH} not found.")
+    endif()
+endif()
+
+# need to re-run CMake if the partition CSV changes, as the offsets/sizes of partitions may change
+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
+function(get_partition_info variable get_part_info_args)
+    separate_arguments(get_part_info_args)
+    execute_process(COMMAND ${PYTHON}
+        ${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()
+
+if(CONFIG_ESP32_PHY_INIT_DATA_IN_PARTITION)
+    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()
+
+get_partition_info(APP_PARTITION_OFFSET "--default-boot-partition --offset")
+
+get_partition_info(OTADATA_PARTITION_OFFSET "--type data --subtype ota --offset")
+
+get_partition_info(OTADATA_PARTITION_SIZE "--type data --subtype ota --size")
+
+endif()

components/pthread/CMakeLists.txt

@@ -0,0 +1,8 @@
+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()

components/sdmmc/CMakeLists.txt

@@ -0,0 +1,4 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_REQUIRES driver)
+register_component()

components/smartconfig_ack/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_PRIV_REQUIRES lwip tcpip_adapter)
+
+register_component()

components/soc/CMakeLists.txt

@@ -0,0 +1,9 @@
+set(SOC_NAME esp32)
+
+set(COMPONENT_SRCDIRS ${SOC_NAME} src)
+set(COMPONENT_ADD_INCLUDEDIRS ${SOC_NAME}/include include)
+
+set(COMPONENT_REQUIRES)
+
+
+register_component()

components/spi_flash/CMakeLists.txt

@@ -0,0 +1,14 @@
+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()

components/spiffs/CMakeLists.txt

@@ -0,0 +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()
+

components/tcpip_adapter/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES lwip)
+
+register_component()

components/ulp/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES)
+
+register_component()

components/vfs/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES)
+
+register_component()

components/wear_levelling/CMakeLists.txt

@@ -0,0 +1,5 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+set(COMPONENT_PRIV_INCLUDEDIRS private_include)
+set(COMPONENT_REQUIRES spi_flash)
+register_component()

components/wpa_supplicant/CMakeLists.txt

@@ -0,0 +1,25 @@
+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 "")
+set(COMPONENT_PRIV_REQUIRES mbedtls)
+
+register_component()
+
+component_compile_options(-Wno-strict-aliasing)
+component_compile_definitions(
+    __ets__
+    EMBEDDED_SUPP
+    IEEE8021X_EAPOL
+    EAP_PEER_METHOD
+    EAP_MSCHAPv2
+    EAP_TTLS
+    EAP_TLS
+    EAP_PEAP
+    USE_WPA2_TASK
+    CONFIG_WPS2
+    CONFIG_WPS_PIN
+    USE_WPS_TASK
+    ESPRESSIF_USE
+    ESP32_WORKAROUND
+    )

components/xtensa-debug-module/CMakeLists.txt

@@ -0,0 +1,6 @@
+set(COMPONENT_SRCDIRS ".")
+set(COMPONENT_ADD_INCLUDEDIRS "include")
+
+set(COMPONENT_REQUIRES "")
+
+register_component()

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,
@@ -48,9 +48,21 @@ copy_if_modified('xml/', 'xml_in/')
 call_with_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)
-call_with_python('../gen-kconfig-doc.py > ' + kconfig_inc_path + '.in')
+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()
+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'
+]
+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

docs/en/api-guides/build-system-cmake.rst

@@ -0,0 +1,959 @@
+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). 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
+=======================
+
+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 :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).
+
+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:
+
+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".
+
+Unlike component ``CMakeLists.txt`` files, when including a ``project_include.cmake`` file the current source directory (``CMAKE_CURRENT_SOURCE_DIR`` and working directory) is the project directory. Use the variable ``COMPONENT_PATH`` for the absolute directory of the component.
+
+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
+^^^^^^^^^^^^^^^^^
+
+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/
+

docs/en/api-guides/core_dump.rst

@@ -92,7 +92,7 @@ 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.                 Offset of coredump partition in flash (type `make partition_table` to see it).
     * --save-core,-s SAVE_CORE.     Save core to file. Othwerwise temporary core file will be deleted. Ignored with "-c".
     * --rom-elf,-r ROM_ELF.         Path to ROM ELF file to use (if skipped "esp32_rom.elf" is used).
     * --print-mem,-m                Print memory dump. Used only with "info_corefile".

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>
    Error Handling <error-handling>
    Fatal Errors <fatal-errors>
    Deep Sleep Wake Stubs <deep-sleep-stub>

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
 

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.
+

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.

docs/en/contribute/style-guide.rst

@@ -185,6 +185,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
 -----------------------------------------------------------
 
@@ -222,3 +235,4 @@ Language features
 
 To be written.
 
+.. _cmake-lint: https://github.com/richq/cmake-lint

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`.

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/
+

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

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)

docs/en/get-started-cmake/get-started-devkitc.rst

@@ -0,0 +1,112 @@
+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 supports various ESP32 modules, including :ref:`esp-modules-and-boards-esp32-wroom-32`, :ref:`ESP32-WROOM-32U <esp-modules-and-boards-esp32-wroom-32d-and-u>`, :ref:`ESP32-WROOM-32D <esp-modules-and-boards-esp32-wroom-32d-and-u>` and :ref:`esp-modules-and-boards-esp32-solo-1`.
+
+
+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-esp32-wroom-32` module soldered to the ESP32-DevKitC V4 board. Optionally ESP32-WROOM-32D, ESP32-WROOM-32U or ESP32-SOLO-1 module may be soldered instead of the ESP32-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

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`
+

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

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

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

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

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<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
+        ~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+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

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`.

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

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`.

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