From b0f2bb2adcb40be2caa924adbb300a7601c03703 Mon Sep 17 00:00:00 2001 From: Natasha Date: Thu, 10 Oct 2019 16:52:07 +0800 Subject: [PATCH] Add translation for getting started guide - batch 1 --- .../get-started/add-idf_path-to-profile.rst | 3 - .../get-started/add-idf_path-to-profile.rst | 73 ----- docs/zh_CN/get-started/eclipse-setup.rst | 6 +- docs/zh_CN/get-started/index.rst | 282 ++++++++++-------- .../zh_CN/get-started/linux-setup-scratch.rst | 31 +- docs/zh_CN/get-started/linux-setup.rst | 92 ++---- .../zh_CN/get-started/macos-setup-scratch.rst | 79 ++--- docs/zh_CN/get-started/macos-setup.rst | 67 ++--- .../get-started/toolchain-setup-scratch.rst | 23 +- .../get-started/windows-setup-scratch.rst | 90 ++++-- .../get-started/windows-setup-update.rst | 42 ++- docs/zh_CN/get-started/windows-setup.rst | 51 ++-- 12 files changed, 384 insertions(+), 455 deletions(-) delete mode 100644 docs/en/get-started/add-idf_path-to-profile.rst delete mode 100644 docs/zh_CN/get-started/add-idf_path-to-profile.rst diff --git a/docs/en/get-started/add-idf_path-to-profile.rst b/docs/en/get-started/add-idf_path-to-profile.rst deleted file mode 100644 index 9d4fa4ff4c..0000000000 --- a/docs/en/get-started/add-idf_path-to-profile.rst +++ /dev/null @@ -1,3 +0,0 @@ -:orphan: - -.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/zh_CN/get-started/add-idf_path-to-profile.rst b/docs/zh_CN/get-started/add-idf_path-to-profile.rst deleted file mode 100644 index 5c051fe533..0000000000 --- a/docs/zh_CN/get-started/add-idf_path-to-profile.rst +++ /dev/null @@ -1,73 +0,0 @@ -在用户配置文件中添加 IDF_PATH 和 idf.py PATH -========================================================================================================== - -:link_to_translation:`en:[英文]` - -使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量： - -- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径 -- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录 - -为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。 - -.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。 - -.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。 - -.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。 - -.. _add-paths-to-profile-windows: - -Windows 操作系统 ------------------------------------ - -在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。 - -在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。 - -你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。 - -- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。 -- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。 - -如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。 - - -.. _add-idf_path-to-profile-linux-macos: - -Linux 和 MacOS 操作系统 ------------------------------------- - -要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$IDF_PATH/tools:$PATH" - -.. note:: - - ``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。 - -请退出，并重新登录使更改生效。 - -.. note:: - - 并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。 - -运行以下命令来检查 ``IDF_PATH`` 设置是否正确:: - - printenv IDF_PATH - -此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。 - -为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令:: - - which idf.py - -这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。 - -如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入:: - - export IDF_PATH=~/esp/esp-idf - export PATH="$IDF_PATH/tools:$PATH" - -如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。 diff --git a/docs/zh_CN/get-started/eclipse-setup.rst b/docs/zh_CN/get-started/eclipse-setup.rst index 0665447085..6014124101 100644 --- a/docs/zh_CN/get-started/eclipse-setup.rst +++ b/docs/zh_CN/get-started/eclipse-setup.rst @@ -4,6 +4,8 @@ Eclipse IDE 创建和烧录指南 :link_to_translation:`en:[English]` -有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。 +ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。 -.. _eclipse.org: https://www.eclipse.org/ +对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 `ESP-IDF Eclipse 插件 `。 + +如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 `，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 ` 章节。 \ No newline at end of file diff --git a/docs/zh_CN/get-started/index.rst b/docs/zh_CN/get-started/index.rst index 06428eb994..9052614b66 100644 --- a/docs/zh_CN/get-started/index.rst +++ b/docs/zh_CN/get-started/index.rst @@ -1,22 +1,20 @@ -******************* -快速入门（CMake） -******************* +*********** +快速入门 +*********** :link_to_translation:`en:[English]` -本文档旨在指导用户搭建 ESP32 硬件开发的软件环境， - -通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。 +本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。 .. include:: /_build/inc/version-note.inc 概述 -==== +============ ESP32 SoC 芯片支持以下功能： * 2.4 GHz Wi-Fi -* 蓝牙 4.2 标准 +* 蓝牙 4.2 * 高性能双核 * 超低功耗协处理器 * 多种外设 @@ -26,18 +24,18 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。 准备工作 -======== +============= 硬件： * 一款 **ESP32** 开发板 -* **USB 数据线** （USB A/Micro USB B） +* **USB 数据线** (A 转 Micro-B) * PC（Windows、Linux 或 Mac OS） 软件： * 设置 **工具链**，用于编译 ESP32 代码； -* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； +* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**； * 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本； * 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse `_。 @@ -51,7 +49,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 开发板简介 -========== +=========================== 请点击下方连接，了解有关具体开发板的详细信息。 @@ -67,17 +65,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _get-started-step-by-step: 详细安装步骤 -============== +========================= 请根据下方详细步骤，完成安装过程。 设置开发环境 -~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* :ref:`get-started-setup-toolchain` +* :ref:`get-started-get-prerequisites` （:doc:`Windows ` 、:doc:`Linux ` 和 :doc:`macOS `） * :ref:`get-started-get-esp-idf` -* :ref:`get-started-setup-path` -* :ref:`get-started-get-packages` +* :ref:`get-started-set-up-tools` +* :ref:`get-started-set-up-env` 创建您的第一个工程 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -90,14 +88,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 * :ref:`get-started-build-monitor` -.. _get-started-setup-toolchain: +.. _get-started-get-prerequisites: -第一步：设置工具链 -==================== +第一步：安装准备 +============================= -工具链指一套用于编译代码和应用程序的程序。 - -为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。 +在正式开始创建工程前，请先完成工具的安装，具体步骤见下： .. toctree:: :hidden: @@ -125,27 +121,22 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、 .. _Linux: ../get-started/linux-setup.html .. _Mac OS: ../get-started/macos-setup.html +.. _get-started-get-esp-idf: + + +第二步：获取 ESP-IDF +================================= + +在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 `_。 + +获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。 + .. note:: 在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。 -此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置` 章节获取更多信息。 - - -.. _get-started-get-esp-idf: -.. _get-started-set-up-tools: - -第二步：获取 ESP-IDF -=========================== - -除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 `_。 - -请将 ESP-IDF 下载到您的本地。 - -获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。 - Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 打开终端，后运行以下命令： @@ -156,71 +147,103 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 Windows 操作系统 -~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 - -请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 - -打开命令提示符，后运行以下命令： - -.. include:: /_build/inc/git-clone-windows.inc - -ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 +除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。 请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 -.. include:: /_build/inc/git-clone-notes.inc +除了使用 ESP-IDF 工具安装器，您也可以参考 :ref:`指南 ` 手动下载 ESP-IDF。 -.. note:: +.. _get-started-set-up-tools: - 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： :: - - cd esp-idf - git submodule update --init - -.. _get-started-setup-path: -.. _get-started-set-up-env: - -第三步：设置环境变量 -=========================== - -请在您的 PC 上设置以下环境变量，否则无法编译工程。 - -- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。 -- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。 - -您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows ` 、:ref:`Linux 及 MacOS ` 操作系统的具体设置方式。 - - -.. _get-started-get-packages: - -第四步：安装 Python 软件包 +第三步：设置工具 ================================= -ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： :: +除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。 - python -m pip install --user -r $IDF_PATH/requirements.txt +Windows 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: +请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。 - 请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如： +除了使用 ESP-IDF 工具安装器，您也可以通过 **命令提示符** 窗口手动安装这些工具。具体步骤见下： - ``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt`` +.. code-block:: batch + + cd %userprofile%\esp\esp-idf + install.bat + +或使用 Windows PowerShell + +.. code-block:: powershell + + cd ~/esp/esp-idf + ./install.ps1 + +Linux 和 MacOS 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + cd ~/esp/esp-idf + ./install.sh + +自定义工具安装路径 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，即 Linux 和 MacOS 系统中的 ``$HOME/.espressif`` 和 Windows 系统的 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。 + +如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行“安装脚本” (``install.bat``、``install.ps1`` 或 ``install.sh``) 和导出脚本 (``export.bat``、``export.ps1`` 或 ``export.sh``) 均保持一致。 + +.. _get-started-set-up-env: + +第四步：设置环境变量 +======================================= + +此时，您刚刚安装的工具尚未添加至 PATH 环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF 提供的另一个脚本完成。 + +Windows 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开始”菜单创建一个 "ESP-IDF Command Prompt" 快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。 + +此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码： + +.. code-block:: batch + + %userprofile%\esp\esp-idf\export.bat + +或使用 Windows PowerShell + +.. code-block:: powershell + + .$HOME/esp/esp-idf/export.ps1 + +Linux 和 MacOS 操作系统 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令： + +.. code-block:: bash + + . $HOME/esp/esp-idf/export.sh + +注意，命令开始的 "." 与路径之间应有一个空格！ + +此外，您也可以将这行代码增加至您的 ``.profile`` 或 ``.bash_profile`` 脚本中，这样您就可以在任何命令窗口使用 ESP-IDF 工具了。 .. _get-started-start-project: 第五步：开始创建工程 -======================= +======================================== 现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。 将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下： Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -228,7 +251,7 @@ Linux 和 MacOS 操作系统 cp -r $IDF_PATH/examples/get-started/hello_world . Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: batch @@ -244,7 +267,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. _get-started-connect: 第六步：连接设备 -====================== +========================================== 现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。 @@ -264,34 +287,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照 .. _get-started-configure: 第七步：配置 -================= +========================= 请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。 Linux 和 MacOS 操作系统 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash cd ~/esp/hello_world idf.py menuconfig -如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。 +如果您的默认 Python 版本为 3.0 及以上，可能需要运行 ``python2 $(which idf.py) menuconfig``。 Windows 操作系统 -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: batch cd %userprofile%\esp\hello_world idf.py menuconfig -Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。 - -.. note:: - - 如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。 - 如果之前的步骤都正确，则会显示下面的菜单： .. figure:: ../../_static/project-configuration.png @@ -299,17 +316,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 :alt: 工程配置 — 主窗口 :figclass: align-center - 工程配置 — 主窗口 +工程配置 — 主窗口 ``menuconfig`` 工具的常见操作见下。 -* ``上下箭头``：移动 +* 上下箭头：移动 * ``回车``：进入子菜单 * ``ESC 键``：返回上级菜单或退出 * ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。 -* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项 -* ``英文问号``：调出有关高亮选项的帮助菜单 -* ``/ 键``：寻找配置项目 +* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项 +* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单 +* ``/ 键``：寻找配置工程 .. attention:: @@ -318,7 +335,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. _get-started-build: 第八步：编译工程 -================== +========================= 请使用以下命令，编译烧录工程：:: @@ -328,23 +345,23 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. 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' + $ 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' 如果一切正常，编译完成后将生成 .bin 文件。 @@ -352,15 +369,15 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. _get-started-flash: 第九步：烧录到设备 -==================== +============================= -请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： :: +请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： - idf.py -p PORT [-b BAUD] flash + ``idf.py -p PORT [-b BAUD] flash`` 请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。 -您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。 +您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。 更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。 @@ -409,11 +426,11 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 .. _get-started-build-monitor: 第十步：监视器 -================== +====================== 您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。 -运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： :: +运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动：:: $ idf.py -p /dev/ttyUSB0 monitor Running idf_monitor in directory [...]/esp/hello_world/build @@ -440,17 +457,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。 -如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板选用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 +如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。 .. figure:: ../../_static/get-started-garbled-output.png :align: center :alt: 乱码输出 :figclass: align-center -此时，请您： +此时，您可以： 1. 退出监视器。 -2. 打开 :ref:`menuconfig `， +2. 打开 :ref:`menuconfig `。 3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。 4. 然后，请重新 :ref:`编译和烧录 ` 应用程序。 @@ -458,7 +475,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 您也可以运行以下命令，一次性执行构建、烧录和监视过程： - ``idf.py -p PORT flash monitor`` + ``idf.py -p PORT flash monitor`` 此外， @@ -470,21 +487,22 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。 更新 ESP-IDF -================= +================ 乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。 -如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH `。否则，工具链将无法找到 ESP-IDF。 - 此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 ` 章节查看。 +注意，更新完成后，请执行 ``install.sh`` （Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。 + +一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 :ref:`get-started-set-up-env`。 + 相关文档 -=========== +================= .. toctree:: :maxdepth: 1 - add-idf_path-to-profile establish-serial-connection eclipse-setup ../api-guides/tools/idf-monitor diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index 1c37b35d37..05d14681a1 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -4,7 +4,7 @@ :link_to_translation:`en:[English]` -除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 +除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 安装准备 ===================== @@ -23,39 +23,38 @@ 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 - .. note:: 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 从源代码编译工具链 ================================= -- 安装依赖： +安装依赖项： - - CentOS 7:: +- CentOS 7:: - sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make + sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make - - Ubuntu pre-16.04:: +- Ubuntu pre-16.04:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make - - Ubuntu 16.04 及以上:: +- Ubuntu 16.04 或以上 :: - sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make + sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - Debian 9:: +- Debian 9:: - sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make + sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make - - Arch:: +- Arch:: - TODO + TODO 创建工作目录，并进入该目录:: - mkdir -p ~/esp - cd ~/esp + mkdir -p ~/esp + cd ~/esp 下载并编译 ``crosstool-NG`` ： @@ -67,7 +66,7 @@ ./ct-ng build chmod -R u+w builds/xtensa-esp32-elf -编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 +编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 后续步骤 diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index 2a05e8fea7..9e48b74ef8 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -1,10 +1,10 @@ -******************************************************************* +********************************************* Linux 平台工具链的标准设置 -******************************************************************* +********************************************* -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -安装前提 +安装准备 ===================== 编译 ESP-IDF 需要以下软件包： @@ -15,94 +15,41 @@ Linux 平台工具链的标准设置 - Ubuntu 和 Debian:: - sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache + sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache - 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 python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache .. note:: 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 -工具链的设置 -========================= - -.. include:: /_build/inc/download-links.inc - -Linux 版的 ESP32 工具链可以从 Espressif 的网站下载： - -- 64 位 Linux： - - |download_link_linux64| - -- 32 位 Linux： - - |download_link_linux32| - -1. 下载完成后，将它解压到 ``~/esp`` 目录： - - - for 64-bit Linux: - - .. include:: /_build/inc/unpack-code-linux64.inc - - - for 32-bit Linux: - - .. include:: /_build/inc/unpack-code-linux32.inc - -.. _setup-linux-toolchain-add-it-to-path: - -2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。 - - 要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：:: - - export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH" - - 或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可:: - - alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"' - - 然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。 - - .. note:: - - 如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。 - -3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确:: - - printenv PATH - - 检查字符串的开头是否包含类似的工具链路径:: - - $ printenv PATH - /home/user-name/esp/xtensa-esp32-elf/bin:/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``，应该有具体的安装的主路径。 - +其他提示 +=============== 权限问题 /dev/ttyUSB0 ----------------------------------------------- +------------------------------------------------------------ -使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 ` +使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 `。 -Arch Linux 用户 --------------------------------- +ncurses 5 依赖项 +-------------------- -在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。 +在 Linux 上运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但一些较新版本默认只提供 ncurses 6。 -`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置： +请查看对应版本信息，确认是否存在可用的 ncurses 5。此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 + +Arch Linux 用户可在 AUR_ 中获得 native 和 lib32 配置的 ncurses 5 库： - https://aur.archlinux.org/packages/ncurses5-compat-libs/ - https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/ -在安装这些软件包之前，你可能需要将作者的公钥添加到你的密钥环中，具体见上方链接中的 "Comments" 部分的介绍。 - -或者，你也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。 - +在安装这些软件包之前，您可能需要将作者的公钥添加到您的密钥环中，具体参考上方的“注释”部分。 后续步骤 -================ +========== -后续开发环境设置，请参考 :ref:`get-started-get-esp-idf` 一节。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 相关文档 @@ -115,3 +62,4 @@ Arch Linux 用户 .. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository + diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index a5003ca94e..0dba12f6b2 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -1,86 +1,87 @@ -********************************************************************* -从零开始设置 Mac OS 环境下的工具链 -********************************************************************* +*********************************************** +从零开始设置 MacOS 环境下的工具链 +*********************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` 软件包管理器 -====================== +=============== -从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 `。 +从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 `。 -MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。 +MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。 - .. _homebrew: https://brew.sh/ - .. _MacPorts: https://www.macports.org/install.php +.. _homebrew: https://brew.sh/ +.. _MacPorts: https://www.macports.org/install.php -请参考 :ref:`工具链自定义设置 ` 章节，查看在哪些情景下需要从头开始设置工具链。 +请参考 :ref:`工具链自定义设置 ` 章节，查看可能需要从头开始设置工具链的情况。 -准备工作 -============================ +安装准备 +===================== - 安装 pip:: - sudo easy_install pip + sudo easy_install pip - 安装 pyserial:: - pip install --user pyserial + pip install --user pyserial - 安装 CMake 和 Ninja 编译工具： - - 若使用 HomeBrew，你可以运行:: + - 若有 HomeBrew，您可以运行:: - brew install cmake ninja + brew install cmake ninja - - 若使用 MacPorts，你可以运行:: + - 若有 MacPorts，您可以运行:: - sudo port install cmake ninja + sudo port install cmake ninja 从源代码编译工具链 -======================================== +================================= -- 相关安装： +安装依赖项： - - 对于 MacPorts:: +- 对于 MacPorts:: - sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make + sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - - 对于 homebrew:: +- 对于 homebrew:: - brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make + brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make 创建一个文件系统镜像（区分大小写）:: - hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" + hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+" 挂载:: - hdiutil mount ~/esp/crosstool.dmg + hdiutil mount ~/esp/crosstool.dmg -创建指向你工作目录的符号链接:: +创建指向您工作目录的符号链接:: - mkdir -p ~/esp - ln -s /Volumes/ctng ~/esp/ctng-volume + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume -前往新创建的目录：:: +前往新创建的目录 :: - cd ~/esp/ctng-volume + cd ~/esp/ctng-volume -下载 ``crosstool-NG``，并开始编译： +下载并编译 ``crosstool-NG`` .. include:: /_build/inc/scratch-build-code.inc -编译工具链：:: +编译工具链:: - ./ct-ng xtensa-esp32-elf - ./ct-ng build - chmod -R u+w builds/xtensa-esp32-elf + ./ct-ng xtensa-esp32-elf + ./ct-ng build + chmod -R u+w builds/xtensa-esp32-elf -编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 ` 中的介绍，将工具链添加到 ``PATH`` 中。 +编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。 后续步骤 -================= +========== + +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 -继续设置开发环境，请前往 :ref:`获取 ESP-IDF ` 章节。 diff --git a/docs/zh_CN/get-started/macos-setup.rst b/docs/zh_CN/get-started/macos-setup.rst index 43d8a6684c..4e9322550b 100644 --- a/docs/zh_CN/get-started/macos-setup.rst +++ b/docs/zh_CN/get-started/macos-setup.rst @@ -1,8 +1,8 @@ -****************************************************************** -在 Mac OS 上安装 ESP32 工具链 -****************************************************************** +********************************************** +MacOS 平台工具链的标准设置 +********************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` 安装准备 ===================== @@ -19,64 +19,30 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 - 安装 CMake 和 Ninja 编译工具： - - 若有 HomeBrew_，你可以运行:: + - 若有 HomeBrew_，您可以运行:: - brew install cmake ninja + brew install cmake ninja - - 若有 MacPorts_，你可以运行:: + - 若有 MacPorts_，您可以运行:: - sudo port install cmake ninja + sudo port install cmake ninja - - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 + - 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。 -- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。 +- 强烈建议同时安装 ccache_ 以获得更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。 .. note:: + + 如您在上述任何步骤中遇到以下错误:: - 如在任一步骤中出现以下报错信息:: - - ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`` - - 你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。 - -安装工具链 -====================== - -.. include:: /_build/inc/download-links.inc - -下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网： - -|download_link_osx| - -完成下载后，请在 ``~/esp`` 目录下进行解压： - -.. include:: /_build/inc/unpack-code-osx.inc - -.. _setup-macos-toolchain-add-it-to-path: - -此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。 - -为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：:: - - export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH - -此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令:: - - alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH" - -此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。 - -注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。 - -此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确:: - - printenv PATH + ``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at:/Library/Developer/CommandLineTools/usr/bin/xcrun`` + 则必须安装 XCode 命令行工具，具体可运行 ``xcode-select --install``。 后续步骤 -================= +========== -前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 相关文档 ================= @@ -91,3 +57,4 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。 .. _ccache: https://ccache.samba.org/ .. _homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php + diff --git a/docs/zh_CN/get-started/toolchain-setup-scratch.rst b/docs/zh_CN/get-started/toolchain-setup-scratch.rst index 435fe177b0..262a3e1376 100644 --- a/docs/zh_CN/get-started/toolchain-setup-scratch.rst +++ b/docs/zh_CN/get-started/toolchain-setup-scratch.rst @@ -1,17 +1,17 @@ .. _get-started-customized-setup: -********************************************************* -工具链自定义设置 -********************************************************* +************************************* +工具链的自定义设置 +************************************* -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。 +除了从乐鑫官网（请见 :ref:`get-started-set-up-tools`）下载二进制工具链外，您还可以自行编译工具链。 -如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链： +如无特殊需求，建议直接使用我们提供的预编译二进制工具链。不过，您可以在以下情况考虑自行编译工具链： - 需要定制工具链编译配置 -- 使用其他 GCC 版本（如 4.8.5） +- 需要使用其他 GCC 版本（如 4.8.5） - 需要破解 gcc、newlib 或 libstdc++ - 有相关兴趣或时间充裕 - 不信任从网站下载的 bin 文件 @@ -19,9 +19,10 @@ 如需自行编译工具链，请查看以下文档： .. toctree:: - :maxdepth: 1 + :maxdepth: 1 + + windows-setup-scratch + linux-setup-scratch + macos-setup-scratch - windows-setup-scratch - linux-setup-scratch - macos-setup-scratch diff --git a/docs/zh_CN/get-started/windows-setup-scratch.rst b/docs/zh_CN/get-started/windows-setup-scratch.rst index 56f5d7d30a..3eab99b94c 100644 --- a/docs/zh_CN/get-started/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started/windows-setup-scratch.rst @@ -1,72 +1,99 @@ -****************************************************************** +******************************************** 从零开始设置 Windows 环境下的工具链 -****************************************************************** +******************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` -本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 ` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。 +除了使用 :doc:`ESP-IDF 工具安装器 `，用户也可以手动设置 Windows 环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。 使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。 +.. note:: + 基于 GNU Make 的构建系统要求 Windows 兼容 MSYS2_ Unix，基于 CMake 的构建系统则无此要求。 + +.. _get-esp-idf-windows-command-line: + +获取 ESP-IDF +================= .. note:: - 基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。 + + 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 + + 请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 + +打开命令提示符，运行以下命令： + +.. include:: /_build/inc/git-clone-windows.inc + +ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 + +请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。 + +.. include:: /_build/inc/git-clone-notes.inc + +.. note:: + + 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 :: + + cd esp-idf + git submodule update --init + 工具 ===== -cmake -^^^^^ +cmake 工具 +^^^^^^^^^^ 下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。 -当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。 +当安装器询问“安装选项”时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。 Ninja 编译工具 -^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: - Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。 + 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。 -从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 `ninja`_。 +从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 ninja_。 -适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 `_ （或者选择你的路径中已有的目录）。 +适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 ` （或者选择您路径中的已有目录）。 Python 2.x ^^^^^^^^^^ -下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。 +下载并运行适用于 Windows 安装器的最新版 Python_ 2.7。 -Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。 +Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到路径中）。请将该选项更改到 "Will be installed"（将会安装）。 -Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令:: +Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”窗口，并运行以下命令:: - pip install --user pyserial + pip install --user pyserial 适用于 IDF 的 MConf -^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -从 `kconfig-frontends 发布页面 `_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。 +从 `kconfig-frontends releases page`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。 -你需将此工具解压到目录，然后 `添加到你的路径 `_。 +请将此工具解压到目录，并 :ref:`添加到您的路径 `。 工具链设置 =============== .. include:: /_build/inc/download-links.inc -下载预编译的 Windows 平台工具链： +下载预编译的 Windows 工具链： |download_link_win32| -解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。 +解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。 -然后，须将该目录下的子目录 ``bin`` `添加到你的路径 `_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 +然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 `。例如，``C:\Program Files\xtensa-esp32-elf\bin``。 .. note:: - - 如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 + 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 .. _add-directory-windows-path: @@ -74,19 +101,24 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并 添加目录到路径 ======================== -添加任何新目录到你的 Windows Path 环境变量： +在 Windows 环境下，向 Path 环境变量增加任何新目录，请： -打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。 +打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。 -双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 +双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 后续步骤 -================ +========== -要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。 +继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 +.. _cmake: https://cmake.org/download/ .. _ninja: https://ninja-build.org/ +.. _ninja-dl: https://github.com/ninja-build/ninja/releases .. _Python: https://www.python.org/downloads/windows/ .. _MSYS2: https://msys2.github.io/ +.. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases +.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ + diff --git a/docs/zh_CN/get-started/windows-setup-update.rst b/docs/zh_CN/get-started/windows-setup-update.rst index 9d4fa4ff4c..8476c30d97 100644 --- a/docs/zh_CN/get-started/windows-setup-update.rst +++ b/docs/zh_CN/get-started/windows-setup-update.rst @@ -1,3 +1,41 @@ -:orphan: +************************************************* +在 Windows 环境下更新 ESP-IDF 工具 +************************************************* + +.. _get-started-install_bat-windows: + +使用脚本安装 ESP-IDF 工具 +==================================== + +请从 Windows “命令提示符”窗口，切换至 ESP-IDF 的安装目录。然后运行:: + + install.bat + +对于 Powershell，请切换至 ESP-IDF 的安装目录。然后运行:: + + install.ps1 + +该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。 +该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。 + +.. _get-started-export_bat-windows: + +使用“导出脚本”将 ESP-IDF 工具添加至 PATH +================================================================================= + +ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。 + +有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。 + +首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``:: + + cd %userprofile%\esp\esp-idf + export.bat + +对于 Powershell 用户，请同样切换至 ESP-IDF 的安装路径，然后执行 ``export.ps1``:: + + cd ~/esp/esp-idf + export.ps1 + +运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。 -.. Remove this file when the Chinese translation of getting started guide is updated diff --git a/docs/zh_CN/get-started/windows-setup.rst b/docs/zh_CN/get-started/windows-setup.rst index 1bbb806fdc..a4297e4e41 100644 --- a/docs/zh_CN/get-started/windows-setup.rst +++ b/docs/zh_CN/get-started/windows-setup.rst @@ -1,54 +1,52 @@ -********************************************************** +*********************************************** Windows 平台工具链的标准设置 -********************************************************** +*********************************************** -:link_to_translation:`en:[英文]` +:link_to_translation:`en:[English]` .. note:: - 基于 CMake 的构建系统仅支持 64 位版本 Windows。 + 目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。 -引言 +概述 ============ -ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。 +ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。 -在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse ` 或支持 CMake 的图形化工具 IDE。 +在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse ` 或其他支持 CMake 的图形化工具 IDE。 -https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip +.. note:: + 较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。 + +.. _get-started-windows-tools-installer: ESP-IDF 工具安装器 ======================= -安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下： +要安装 ESP-IDF 必备工具，最简易的方式是下载 ESP-IDF 工具安装器，地址如下： -https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe +https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe -安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。 +本安装器可为您安装所需的交叉编译器、OpenOCD、cmake_ 和 Ninja_ 编译工具，以及一款 mconf-idf_ 配置工具。此外，本安装器还可在有需要时下载、运行 Python_ 3.7 和 `Git For Windows` 的安装器。 -安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。 +本安装器还可用于下载任意 ESP-IDF 发布版本。 -请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。 +使用命令提示符 +======================== -安装 Git -============== +在后续步骤中，我们将使用 Windows 的命令提示符进行操作。 -ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。 +ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 命令提示符窗口的快捷方式。本快捷方式可以打开 Windows 命令提示符（即 cmd.exe），并运行 ``export.bat`` 脚本以设置各环境变量（比如 ``PATH``，``IDF_PATH`` 等）。此外，您可还以通过 Windows 命令提示符使用各种已经安装的工具。 -如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。 +注意，本快捷方式仅适用 ESP-IDF 工具安装器中指定的 ESP-IDF 路径。如果您的电脑上存在多个 ESP-IDF（比如您需要不同的 ESP-IDF 版本）需要使用快捷方式，您可以： -使用终端 -================ +1. 为 ESP-IDF 工具安装器创建的快捷方式创建一个副本，并将新快捷方式的“当前路径”指定为您希望使用的 ESP-IDF 路径。 -在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符： - -- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。 -- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。 -- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。 +2. 运行 ``cmd.exe``，并更新至您希望使用的 ESP-IDF 目录，然后运行 ``export.bat``。注意，这种方法要求 ``PATH`` 中存在 Python 和 Git。如果您在使用时遇到有关“找不到 Python 或 Git” 的错误信息，请使用第一种方法。 后续步骤 ========== -要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。 +当 ESP-IDF 工具安装器安装完成后，则开发环境设置也到此结束。后续开发步骤，请前往 :ref:`get-started-start-project` 查看。 相关文档 ================= @@ -59,7 +57,7 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你 :maxdepth: 1 windows-setup-scratch - + windows-setup-update .. _MSYS2: https://msys2.github.io/ .. _cmake: https://cmake.org/download/ @@ -68,3 +66,4 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你 .. _Git for Windows: https://gitforwindows.org/ .. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/ .. _Github Desktop: https://desktop.github.com/ +