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

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

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

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

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