Merge branch 'bugfix/doc_python3' into 'master'

Docs: Encourage to use Python 3

Closes IDF-1316

See merge request espressif/esp-idf!7726
This commit is contained in:
Krzysztof Budzynski 2020-02-26 05:04:18 +08:00
commit 097d0bd9c8
23 changed files with 52 additions and 50 deletions

View file

@ -45,12 +45,11 @@ mainmenu "Espressif IoT Development Framework Configuration"
a crosstool-ng gcc setup that is in your PATH. a crosstool-ng gcc setup that is in your PATH.
config SDK_PYTHON config SDK_PYTHON
string "Python 2 interpreter" string "Python interpreter"
depends on !IDF_CMAKE depends on !IDF_CMAKE
default "python" default "python"
help help
The executable name/path that is used to run python. On some systems Python 2.x The executable name/path that is used to run python.
may need to be invoked as python2.
(Note: This option is used with the legacy GNU Make build system only.) (Note: This option is used with the legacy GNU Make build system only.)

View file

@ -178,14 +178,15 @@ For more detailed information about integrating ESP-IDF with CMake into an IDE,
.. _setting-python-interpreter: .. _setting-python-interpreter:
Setting the Python Interpreter Setting up 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. ESP-IDF works well with all supported Python versions. It should work out-of-box even if you have a legacy system where the default ``python`` interpreter is still Python 2.7, however, it is advised to switch to Python 3 if possible.
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. ``idf.py`` and other Python scripts will run with the default Python interpreter, i.e. ``python``. You can switch to a
different one like ``python3 $IDF_PATH/tools/idf.py ...``, or 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 CMake directly, running ``cmake -D PYTHON=python3 ...`` 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. 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.

View file

@ -180,10 +180,10 @@ The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.t
.. note:: .. note::
Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run
the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7`` the command ``python --version`` and depending on the result, you might want to use ``python3``, ``python3.7``
or similar instead of just ``python``, e.g.:: or similar instead of just ``python``, e.g.::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt python3 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project-legacy: .. _get-started-start-project-legacy:
@ -283,10 +283,6 @@ To navigate and use ``menuconfig``, press the following keys:
* ``?`` while highlighting a configuration item to display help about that item * ``?`` while highlighting a configuration item to display help about that item
* ``/`` to find configuration items * ``/`` to find configuration items
.. note::
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
.. attention:: .. attention::
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples. If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.

View file

@ -20,7 +20,7 @@ To compile with ESP-IDF you need to get the following packages:
- Arch:: - Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools
.. note:: .. note::

View file

@ -20,7 +20,7 @@ To compile with ESP-IDF you need to get the following packages:
- Arch:: - Arch::
sudo pacman -S --needed gcc git make flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools sudo pacman -S --needed gcc git make flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools
.. note:: .. note::

View file

@ -314,8 +314,6 @@ Linux and macOS
cd ~/esp/hello_world cd ~/esp/hello_world
idf.py menuconfig idf.py menuconfig
If your default version of Python is 3.x, you may need to run ``python2 $(which idf.py) menuconfig`` instead.
Windows Windows
~~~~~~~ ~~~~~~~

View file

@ -23,7 +23,7 @@ To compile with ESP-IDF you need to get the following packages:
- Arch:: - Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja ccache
.. note:: .. 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". 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".

View file

@ -11,15 +11,15 @@ To compile with ESP-IDF you need to get the following packages:
- CentOS 7:: - CentOS 7::
sudo yum install git wget flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache sudo yum install git wget flex bison gperf python cmake ninja-build ccache
- Ubuntu and Debian:: - Ubuntu and Debian::
sudo apt-get install git wget flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache libffi-dev libssl-dev sudo apt-get install git wget flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev
- Arch:: - Arch::
sudo pacman -S --needed gcc git make flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache
.. note:: .. 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". 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".
@ -32,6 +32,20 @@ Permission issues /dev/ttyUSB0
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`. With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
Setting up Python 3 as default for Ubuntu and Debian
----------------------------------------------------
Ubuntu and Debian are still providing Python 2.7 as the default interpreter. Python 3 can be installed as follows::
sudo apt-get install python3 python3-pip python3-setuptools
Making Python 3 the default interpreter is possible by running::
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10
.. note::
This is system-wide change which may affect all of the applications.
Next Steps Next Steps
========== ==========

View file

@ -61,10 +61,10 @@ Download the ninja_ latest stable Windows release from the (`download page <ninj
The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then :ref:`added to your Path <add-directory-windows-path>` (or you can choose a directory which is already on your Path). The Ninja for Windows download is a .zip file containing a single ``ninja.exe`` file which needs to be unzipped to a directory which is then :ref:`added to your Path <add-directory-windows-path>` (or you can choose a directory which is already on your Path).
Python 2.x Python
^^^^^^^^^^ ^^^^^^
Download the latest Python_ 2.7 for Windows installer, and run it. Download the latest Python_ for Windows installer, and run it.
The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed". The "Customise" step of the Python installer gives a list of options. The last option is "Add python.exe to Path". Change this option to select "Will be installed".

View file

@ -323,9 +323,9 @@ Doxygen 的安装取决于操作系统:
:: ::
$ pacman -S mingw32/mingw-w64-i686-python2-pillow $ pacman -S mingw32/mingw-w64-i686-python-pillow
查看屏幕上的记录,确定 ``mingw-w64-i686-python2-pillow-4.3.0-1`` 已安装。旧版本 *pillow* 无法运行。 查看屏幕上的记录,确定 ``mingw-w64-i686-python-pillow-4.3.0-1`` 已安装。旧版本 *pillow* 无法运行。
Windows 安装 Doxygen 的缺点是 `blockdiag pictures <add-illustrations>` 字体不能正确加载,可能会存在乱码。在此问题解决之前,您可以使用 `interactive shell`_ 查看完整图片。 Windows 安装 Doxygen 的缺点是 `blockdiag pictures <add-illustrations>` 字体不能正确加载,可能会存在乱码。在此问题解决之前,您可以使用 `interactive shell`_ 查看完整图片。

View file

@ -178,9 +178,9 @@ ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您
.. note:: .. note::
请注意查询您所使用的 Python 解释器的版本(运行命令 ``python --version``),并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``,例如:: 请注意查询您所使用的 Python 解释器的版本(运行命令 ``python --version``),并根据查询结果将上方命令中的 ``python`` 替换为 ``python3``, ``python3.7``,例如::
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt python3 -m pip install --user -r $IDF_PATH/requirements.txt
.. _get-started-start-project-legacy: .. _get-started-start-project-legacy:
@ -278,10 +278,6 @@ Windows 操作系统
* ``英文问号`` (查询配置选项):调出有关该选项的帮助菜单 * ``英文问号`` (查询配置选项):调出有关该选项的帮助菜单
* ``/ 键``:寻找配置工程 * ``/ 键``:寻找配置工程
.. note::
如果您是 **Arch Linux** 用户,请前往 ``SDK tool configuration``,并将 ``Python 2 interpreter`` 的名称从 ``python`` 替换为 ``python2``
.. attention:: .. attention::
如果您使用的是 ESP32-DevKitC板载 ESP32-SOLO-1 模组),请在烧写示例程序前,前往 ``menuconfig`` 中使能单核模式(:ref:`CONFIG_FREERTOS_UNICORE`)。 如果您使用的是 ESP32-DevKitC板载 ESP32-SOLO-1 模组),请在烧写示例程序前,前往 ``menuconfig`` 中使能单核模式(:ref:`CONFIG_FREERTOS_UNICORE`)。

View file

@ -20,7 +20,7 @@
- Arch:: - Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools
.. note:: .. note::

View file

@ -20,7 +20,7 @@ Linux 平台工具链的标准设置(传统 GNU Make
- Arch:: - Arch::
sudo pacman -S --needed gcc git make flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools sudo pacman -S --needed gcc git make flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools
.. note:: .. note::

View file

@ -311,8 +311,6 @@ Linux 和 MacOS 操作系统
cd ~/esp/hello_world cd ~/esp/hello_world
idf.py menuconfig idf.py menuconfig
如果您的默认 Python 版本为 3.0 及以上,可能需要运行 ``python2 $(which idf.py) menuconfig``
Windows 操作系统 Windows 操作系统
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View file

@ -21,7 +21,7 @@
- Arch:: - Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja ccache
.. note:: .. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库,或安装 "cmake3" 软件包,而不是安装 "cmake"。 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库,或安装 "cmake3" 软件包,而不是安装 "cmake"。

View file

@ -11,15 +11,15 @@ Linux 平台工具链的标准设置
- CentOS 7:: - CentOS 7::
sudo yum install git wget flex bison gperf python pyserial python-pyelftools cmake ninja-build ccache sudo yum install git wget flex bison gperf python cmake ninja-build ccache
- Ubuntu 和 Debian:: - Ubuntu 和 Debian::
sudo apt-get install git wget flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache libffi-dev libssl-dev sudo apt-get install git wget flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev
- Arch:: - Arch::
sudo pacman -S --needed gcc git make flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache sudo pacman -S --needed gcc git make flex bison gperf python-pip python-pyserial cmake ninja ccache
.. note:: .. note::
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库,或安装 "cmake3" 软件包,而不是安装 "cmake"。 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库,或安装 "cmake3" 软件包,而不是安装 "cmake"。

View file

@ -61,10 +61,10 @@ Ninja 编译工具
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件,包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录,并 :ref:`添加到您的路径 <add-directory-windows-path>` (或者选择您路径中的已有目录)。 适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件,包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录,并 :ref:`添加到您的路径 <add-directory-windows-path>` (或者选择您路径中的已有目录)。
Python 2.x Python
^^^^^^^^^^ ^^^^^^
下载并运行适用于 Windows 安装器的最新版 Python_ 2.7 下载并运行适用于 Windows 安装器的最新版 Python_。
Python 安装器的“自定义”菜单可为您提供一系列选项,最后一项为 "Add python.exe to Path"(添加 python.exe 到路径中)。请将该选项更改到 "Will be installed"(将会安装)。 Python 安装器的“自定义”菜单可为您提供一系列选项,最后一项为 "Add python.exe to Path"(添加 python.exe 到路径中)。请将该选项更改到 "Will be installed"(将会安装)。

View file

@ -18,7 +18,7 @@ python scripts/esp_local_ctrl.py
Sample output: Sample output:
``` ```
python2 scripts/esp_local_ctrl.py python scripts/esp_local_ctrl.py
==== Acquiring properties information ==== ==== Acquiring properties information ====

View file

@ -8,7 +8,7 @@ This sort of persistency enables the server to have independent sessions/context
* In order to test the HTTPD server persistent sockets demo : * In order to test the HTTPD server persistent sockets demo :
1. compile and burn the firmware `idf.py -p PORT flash` 1. compile and burn the firmware `idf.py -p PORT flash`
2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80
3. run the test script "python2 scripts/adder.py \<IP\> \<port\> \<N\>" 3. run the test script "python scripts/adder.py \<IP\> \<port\> \<N\>"
* the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent * the provided test script sends (POST) numbers from 1 to N to the server which has a URI POST handler for adding these numbers into an accumulator that is valid throughout the lifetime of the connection socket, hence persistent
* the script does a GET before closing and displays the final value of the accumulator * the script does a GET before closing and displays the final value of the accumulator

View file

@ -10,7 +10,7 @@ The Example consists of HTTPD server demo with demostration of URI handling :
1. compile and burn the firmware `idf.py -p PORT flash` 1. compile and burn the firmware `idf.py -p PORT flash`
2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80 2. run `idf.py -p PORT monitor` and note down the IP assigned to your ESP module. The default port is 80
3. test the example : 3. test the example :
* run the test script : "python2 scripts/client.py \<IP\> \<port\> \<MSG\>" * run the test script : "python scripts/client.py \<IP\> \<port\> \<MSG\>"
* the provided test script first does a GET \hello and displays the response * the provided test script first does a GET \hello and displays the response
* the script does a POST to \echo with the user input \<MSG\> and displays the response * the script does a POST to \echo with the user input \<MSG\> and displays the response
* or use curl (asssuming IP is 192.168.43.130): * or use curl (asssuming IP is 192.168.43.130):

View file

@ -24,7 +24,7 @@ Prerequisites
- Linux / MacOS / Windows (standard distributions) - Linux / MacOS / Windows (standard distributions)
* The following packages are needed to use this utility: * The following packages are needed to use this utility:
- Python version: 2.7 (minimum) is required. You can find it here: <https://www.python.org/downloads/> - Python: <https://www.python.org/downloads/>
.. note:: .. note::

View file

@ -24,7 +24,7 @@
- Linux、MacOS 或 Windows标准版 - Linux、MacOS 或 Windows标准版
* 安装依赖包: * 安装依赖包:
- Python最低版本要求为 2.7。下载地址:https://www.python.org/downloads/。 - Python https://www.python.org/downloads/。
.. note:: .. note::

View file

@ -34,7 +34,7 @@ set -e
pacman --noconfirm -Syu # This step may require the terminal to be closed and restarted pacman --noconfirm -Syu # This step may require the terminal to be closed and restarted
pacman --noconfirm -S --needed gettext-devel gcc git make ncurses-devel flex bison gperf vim \ pacman --noconfirm -S --needed gettext-devel gcc git make ncurses-devel flex bison gperf vim \
mingw-w64-i686-python2-pip mingw-w64-i686-python2-cryptography unzip winpty mingw-w64-i686-python-pip mingw-w64-i686-python-cryptography unzip winpty
# if IDF_PATH is set, install requirements now as well # if IDF_PATH is set, install requirements now as well
if [ -n "$IDF_PATH" ]; then if [ -n "$IDF_PATH" ]; then