docs: Add some tips about setting the Python interpreter, and a specific check in...

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

diff --git a/Kconfig b/Kconfig
index 75606aa4ff3d66752e5afb8b3a54a9672aa473f0..f6ebbc5731d417432bcf3158cd80bf1d050bb9eb 100644 (file)
--- 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 077e34b514fdf6f41f58e4fd6c50b751cf578d91..f32cc9eb31174a07f08a94190f4564a03f08be77 100644 (file)
--- 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 d5fbf279a3fbf67d25d1e993917e79f5181386cc..bd7b9fe239425b30c2a6d7d44745dbae71aa5b9f 100755 (executable)
--- 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 29347efc94c4291a840a089d82f99cfd20309320..278626657f8fc7421b07d312fba2a485a1f09a91 100755 (executable)
--- 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