cmake: Fix "make flash" & "ninja flash" targets

As reported on forum.

Requires a small CMake wrapper script to pick
up environment variables at flashing time.

components/esptool_py/project_include.cmake

@@ -43,9 +43,14 @@ add_custom_target(app ALL DEPENDS "${PROJECT_NAME}.bin")
 #
 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}
+        COMMAND ${CMAKE_COMMAND}
+        -D IDF_PATH="${IDF_PATH}"
+        -D ESPTOOLPY="${ESPTOOLPY}"
+        -D ESPTOOL_ARGS="write_flash;@flash_${flasher_filename}_args"
+        -D ESPTOOL_WORKING_DIR="${CMAKE_CURRENT_BINARY_DIR}"
+        -P run_esptool.cmake
+        WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}
+        USES_TERMINAL
         )
 endfunction()
 

components/esptool_py/run_esptool.cmake

@@ -0,0 +1,45 @@
+# A CMake script to run esptool commands from within ninja or make
+# or another cmake-based build runner
+#
+# (Needed to expand environment variables, for backwards compatibility.)
+#
+# It is recommended to NOT USE this CMake script if you have the option of
+# running esptool.py directly. This script exists only for use inside CMake builds.
+#
+cmake_minimum_required(VERSION 3.5)
+
+if(NOT IDF_PATH OR NOT ESPTOOLPY OR NOT ESPTOOL_ARGS OR NOT ESPTOOL_WORKING_DIR)
+    message(FATAL_ERROR "IDF_PATH, ESPTOOLPY, ESPTOOL_ARGS, and ESPTOOL_WORKING_DIR must "
+        "be specified on the CMake command line. For direct esptool execution, it is "
+        "strongly recommended to run esptool.py directly.")
+endif()
+
+# Note: we can't expand these environment variables in the main IDF CMake build,
+# because we want to expand them at flashing time not at CMake runtime (so they can change
+# without needing a CMake re-run)
+if(NOT ENV{ESPPORT})
+    message("Note: esptool.py will search for a serial port. To specify a port, set the ESPPORT environment variable.")
+else()
+    set(port_arg "-p $ENV{ESPPORT}")
+endif()
+
+set(ESPBAUD $ENV{ESPBAUD})
+if(NOT ESPBAUD)
+    message("Note: Using default baud rate 460800. To modify, set ESPBAUD environment variable.")
+    set(ESPBAUD 460800)
+endif()
+
+include("${IDF_PATH}/tools/cmake/utilities.cmake")
+
+set(cmd "${ESPTOOLPY} ${port_arg} -b ${ESPBAUD} ${ESPTOOL_ARGS}")
+spaces2list(cmd)
+
+execute_process(COMMAND ${cmd}
+    WORKING_DIRECTORY "${ESPTOOL_WORKING_DIR}"
+    RESULT_VARIABLE result
+    )
+
+if(${result})
+    # No way to have CMake silently fail, unfortunately
+    message(FATAL_ERROR "esptool.py failed")
+endif()

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

@@ -120,6 +120,34 @@ If using CMake with ``ninja`` or ``make``, there are also targets for more of th
 .. 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.
 
+.. _flash-with-ninja-or-make:
+
+Flashing with ninja or make
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's possible to build and flash directly from ninja or make by running a target like::
+
+  ninja flash
+
+Or::
+
+  make app-flash
+
+Available targets are: ``flash``, ``app-flash`` (app only), ``bootloader-flash`` (bootloader only).
+
+When flashing this way, optionally set the ``ESPPORT`` and ``ESPBAUD`` environment variables to specify the serial port and baud rate. You can set environment variables in your operating system or IDE project. Alternatively, set them directly on the command line::
+
+  ESPPORT=/dev/ttyUSB0 ninja flash
+
+.. note:: Providing environment variables at the start of the command like this is Bash shell Syntax. It will work on Linux and macOS. It won't work when using Windows Command Prompt, but it will work when using Bash-like shells on Windows.
+
+Or::
+
+  make -j3 app-flash ESPPORT=COM4 ESPBAUD=2000000
+
+.. note:: Providing variables at the end of the command line is ``make`` syntax, and works for ``make`` on all platforms.
+
+
 Using CMake in an IDE
 ---------------------
 
@@ -918,6 +946,11 @@ No Longer Necessary
 
 It is no longer necessary to set ``COMPONENT_SRCDIRS`` if setting ``COMPONENT_SRCS`` (in fact, in the CMake-based system ``COMPONENT_SRCS`` is ignored if ``COMPONENT_SRCDIRS`` is set).
 
+Flashing from make
+------------------
+
+``make flash`` and similar targets still work to build and flash. However, project ``sdkconfig`` no longer specifies serial port and baud rate. Environment variables can be used to override these. See :ref:`flash-with-ninja-or-make` for more details.
+
 .. _esp-idf-template: https://github.com/espressif/esp-idf-template
 .. _cmake: https://cmake.org
 .. _ninja: https://ninja-build.org