From c7bebb041360de72c5cfc6e6d84c1df6668a5090 Mon Sep 17 00:00:00 2001 From: Dai Zi Yan Date: Mon, 30 Nov 2020 17:58:27 +0800 Subject: [PATCH] Doc/update CN translation for files on setting up toolchain from scratch in get started --- docs/en/get-started/macos-setup-scratch.rst | 10 ++-- docs/en/get-started/windows-setup-scratch.rst | 6 +-- docs/en/get-started/windows-setup-update.rst | 2 + .../zh_CN/get-started/linux-setup-scratch.rst | 39 ++++++++++++--- .../zh_CN/get-started/macos-setup-scratch.rst | 22 ++++----- .../get-started/windows-setup-scratch.rst | 49 ++++++++----------- .../get-started/windows-setup-update.rst | 25 +++++----- 7 files changed, 87 insertions(+), 66 deletions(-) diff --git a/docs/en/get-started/macos-setup-scratch.rst b/docs/en/get-started/macos-setup-scratch.rst index 1223730384..080cfc667a 100644 --- a/docs/en/get-started/macos-setup-scratch.rst +++ b/docs/en/get-started/macos-setup-scratch.rst @@ -7,11 +7,11 @@ Setup Toolchain for Mac OS from Scratch Package Manager =============== -To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or homebrew_ package manager. +To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain`, you will need to install either the MacPorts_ or Homebrew_ package manager. -MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools. +MacPorts needs a full XCode installation, while Homebrew only needs XCode command line tools. - .. _homebrew: https://brew.sh/ + .. _Homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php See :ref:`Customized Setup of Toolchain ` section for some of the reasons why installing the toolchain from scratch may be necessary. @@ -29,7 +29,7 @@ Install Prerequisites - install CMake & Ninja build: - - If you have HomeBrew, you can run:: + - If you have Homebrew, you can run:: brew install cmake ninja dfu-util @@ -46,7 +46,7 @@ Compile the Toolchain from Source sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make - - with homebrew:: + - with Homebrew:: brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make diff --git a/docs/en/get-started/windows-setup-scratch.rst b/docs/en/get-started/windows-setup-scratch.rst index 29fa00da0c..8166716591 100644 --- a/docs/en/get-started/windows-setup-scratch.rst +++ b/docs/en/get-started/windows-setup-scratch.rst @@ -43,7 +43,7 @@ Consult :doc:`/versions` for information about which ESP-IDF version to use in a Tools ===== -cmake +CMake ^^^^^ Download the latest stable release of CMake_ for Windows and run the installer. @@ -56,7 +56,7 @@ Ninja build .. note:: Ninja currently only provides binaries for 64-bit Windows. It is possible to use CMake and ``idf.py`` with other build tools, such as mingw-make, on 32-bit windows. However this is currently undocumented. -Download the ninja_ latest stable Windows release from the (`download page `_). +Download the Ninja_ latest stable Windows release from the (`download page `_). 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 ` (or you can choose a directory which is already on your Path). @@ -107,7 +107,7 @@ Next Steps To carry on with development environment setup, proceed to :ref:`get-started-set-up-tools`. .. _CMake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ +.. _Ninja: https://ninja-build.org/ .. _ninja-dl: https://github.com/ninja-build/ninja/releases .. _Python: https://www.python.org/downloads/windows/ .. _MSYS2: https://www.msys2.org/ diff --git a/docs/en/get-started/windows-setup-update.rst b/docs/en/get-started/windows-setup-update.rst index 531573e7dc..1c50110ac6 100644 --- a/docs/en/get-started/windows-setup-update.rst +++ b/docs/en/get-started/windows-setup-update.rst @@ -2,6 +2,8 @@ Updating ESP-IDF tools on Windows ********************************* +:link_to_translation:`zh_CN:[中文]` + .. _get-started-install_bat-windows: Install ESP-IDF tools using a script diff --git a/docs/zh_CN/get-started/linux-setup-scratch.rst b/docs/zh_CN/get-started/linux-setup-scratch.rst index ae619972b3..b95d17fd52 100644 --- a/docs/zh_CN/get-started/linux-setup-scratch.rst +++ b/docs/zh_CN/get-started/linux-setup-scratch.rst @@ -6,6 +6,8 @@ 除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。 +.. 注解:: 设置自己的工具链可以解决 Y2K38 问题（time_t 从 32 位扩展到 64 位）。 + 安装准备 ===================== @@ -23,8 +25,8 @@ sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja ccache dfu-util -.. note:: - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。 +.. 注解:: + 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库，或开启 backports 套件库，或安装 "cmake3" 软件包（而不是安装 "cmake")。 从源代码编译工具链 ================================= @@ -56,23 +58,46 @@ mkdir -p ~/esp cd ~/esp -下载并编译 ``crosstool-NG`` ： +下载并编译 ``crosstool-NG``： .. include-build-file:: inc/scratch-build-code.inc +.. 注解:: 在设置支持 64 位 time_t 的工具链时，您需要将 ``crosstool-NG/samples/xtensa-esp32-elf/crosstool.config`` 文件中第 33 和 43 行的可选参数 ``--enable-newlib-long-time_t`` 删除。 + 编译工具链:: ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf ./ct-ng build chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf -.. only:: esp32 - 编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。请按照 :ref:`标准设置指南 ` 的介绍，将工具链添加到 ``PATH``。 +编译得到的工具链会被保存至 ``~/esp/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``。 +添加工具链到 PATH 环境变量 +=========================== + +需要将自定义工具链复制到一个二进制目录中，并将其添加到 ``PATH`` 中。例如，您可以将编译好的工具链复制到 ``~/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/`` 目录中。 + +为了正常使用工具链，您需要更新 ``~/.profile`` 文件中 ``PATH`` 环境变量。此外，您还可以在 ``~/.profile`` 文件中增加以下代码。这样，所有终端窗口均可以使用 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``:: + + export PATH="$HOME/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin:$PATH" + +.. 注解:: + + 如果您已将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile`` 两个文件，则请更新 ``.bash_profile``。在 CentOS 环境下, ``alias`` 需要添加到 ``.bashrc`` 文件中。 + +退出并重新登录以使 ``.profile`` 的更改生效。运行以下命令来检查 ``PATH`` 设置是否正确:: + + printenv PATH + +此时您需要检查输出结果的开头中是否包含类似如下的工具链路径:: + + $ printenv PATH + /home/user-name/esp/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-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`` 应该替换成您安装的主路径。 后续步骤 ========== -继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 - +请前往 :ref:`get-started-get-esp-idf` 章节继续设置开发环境。 \ No newline at end of file diff --git a/docs/zh_CN/get-started/macos-setup-scratch.rst b/docs/zh_CN/get-started/macos-setup-scratch.rst index 68c0d5abab..19067b44d7 100644 --- a/docs/zh_CN/get-started/macos-setup-scratch.rst +++ b/docs/zh_CN/get-started/macos-setup-scratch.rst @@ -7,11 +7,11 @@ 软件包管理器 =============== -从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 `。 +从零开始设置工具链，您需要安装 MacPorts_ 或 Homebrew_ 软件包管理器。或者，您也可以直接下载 :doc:`预编译的工具链 `。 -MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。 +MacPorts 需要完整的 XCode 软件，而 Homebrew 只需要安装 XCode 命令行工具即可。 -.. _homebrew: https://brew.sh/ +.. _Homebrew: https://brew.sh/ .. _MacPorts: https://www.macports.org/install.php 请参考 :ref:`工具链自定义设置 ` 章节，查看可能需要从头开始设置工具链的情况。 @@ -29,7 +29,7 @@ MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命 - 安装 CMake 和 Ninja 编译工具： - - 若有 HomeBrew，您可以运行:: + - 若有 Homebrew，您可以运行:: brew install cmake ninja dfu-util @@ -46,13 +46,13 @@ MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命 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 创建一个文件系统镜像（区分大小写）:: - 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+" 挂载:: @@ -60,14 +60,14 @@ MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命 创建指向您工作目录的符号链接:: - mkdir -p ~/esp - ln -s /Volumes/ctng ~/esp/ctng-volume + mkdir -p ~/esp + ln -s /Volumes/ctng ~/esp/ctng-volume -前往新创建的目录 :: +前往新创建的目录:: cd ~/esp/ctng-volume -下载并编译 ``crosstool-NG`` +下载并编译 ``crosstool-NG``: .. include-build-file:: inc/scratch-build-code.inc @@ -83,5 +83,5 @@ MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命 后续步骤 ========== -继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。 +请前往 :ref:`get-started-get-esp-idf` 章节继续设置开发环境。 diff --git a/docs/zh_CN/get-started/windows-setup-scratch.rst b/docs/zh_CN/get-started/windows-setup-scratch.rst index f53d8da026..177ee2b05d 100644 --- a/docs/zh_CN/get-started/windows-setup-scratch.rst +++ b/docs/zh_CN/get-started/windows-setup-scratch.rst @@ -4,7 +4,7 @@ :link_to_translation:`en:[English]` -除了使用 :doc:`ESP-IDF 工具安装器 `，用户也可以手动设置 Windows 环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。 +除了使用 :doc:`ESP-IDF 工具安装器 `，用户也可以手动设置 Windows 环境下的工具链，这正是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。 使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。 @@ -16,9 +16,9 @@ 获取 ESP-IDF ================= -.. note:: +.. 注解:: - 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 + 较早版本 ESP-IDF 使用了 **MSYS2 bash 终端命令行**。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。 请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。 @@ -32,9 +32,9 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 .. include-build-file:: inc/git-clone-notes.inc -.. note:: +.. 注解:: - 在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 :: + 在克隆远程仓库时，请加上可选参数 ``--recursive`` 。如果你已经克隆了 ESP-IDF 但没有加上此参数，请运行以下命令获取所有子模块 :: cd esp-idf git submodule update --init @@ -43,7 +43,7 @@ ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。 工具 ===== -cmake 工具 +CMake 工具 ^^^^^^^^^^ 下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。 @@ -53,12 +53,12 @@ cmake 工具 Ninja 编译工具 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. note:: - 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。 +.. 注解:: + 目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具（如 mingw-make）在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` 。但是目前暂无关于此工具的说明文档。 -从（`下载页面 `_）下载最新发布的 Windows 平台稳定版 ninja_。 +请从 `下载页面 `_ 下载最新发布的 Windows 平台稳定版 Ninja_。 -适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 ` （或者选择您路径中的已有目录）。 +适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到 Path 环境变量 ` （或者选择解压到 Path 变量中已有的目录）。 Python @@ -66,18 +66,12 @@ Python 下载并运行适用于 Windows 安装器的最新版 Python_。 -Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到路径中）。请将该选项更改到 "Will be installed"（将会安装）。 +Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到 Path 环境变量中），请将该选项更改为 "Will be installed"（将会安装）。 Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”窗口，并运行以下命令:: pip install --user pyserial -适用于 IDF 的 MConf -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -从 `kconfig-frontends releases page`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。 - -请将此工具解压到目录，并 :ref:`添加到您的路径 `。 工具链设置 =============== @@ -88,38 +82,37 @@ Python 安装完成后，从 Windows 开始菜单中打开“命令提示符” |download_link_win32| -解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` 目录。 +将压缩包文件解压到 ``C:\Program Files``（或其他位置）。压缩包文件包含一个 ``xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`` 目录。 -然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 `。例如，``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``。 +然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到 Path 环境变量 `。例如，将目录 ``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 添加到 Path 环境变量。 -.. note:: - 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。 +.. 注解:: + 如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin`` 到 Path 环境变量，因为 MSYS2 环境已包含工具链。 .. _add-directory-windows-path: -添加目录到路径 +添加目录到 Path 环境变量 ======================== 在 Windows 环境下，向 Path 环境变量增加任何新目录，请： 打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。 -双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;``。 +双击 ``Path`` 变量（选择“用户路径”或“系统路径”，具体取决于您是否希望其他用户的 Path 中也存在该目录)。最后在值的末尾增加 ``;``。 后续步骤 ========== -继续设置开发环境，请前往 :ref:`get-started-set-up-tools` 章节。 +请前往 :ref:`get-started-set-up-tools` 章节继续设置开发环境。 -.. _cmake: https://cmake.org/download/ -.. _ninja: https://ninja-build.org/ +.. _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://www.msys2.org/ .. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases .. Note: These two targets may be used from git-clone-notes.inc depending on version, don't remove .. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/ -.. _Releases page: https://github.com/espressif/esp-idf/releases - +.. _Releases page: https://github.com/espressif/esp-idf/releases \ No newline at end of file diff --git a/docs/zh_CN/get-started/windows-setup-update.rst b/docs/zh_CN/get-started/windows-setup-update.rst index 8476c30d97..f51edafba0 100644 --- a/docs/zh_CN/get-started/windows-setup-update.rst +++ b/docs/zh_CN/get-started/windows-setup-update.rst @@ -2,6 +2,8 @@ 在 Windows 环境下更新 ESP-IDF 工具 ************************************************* +:link_to_translation:`en:[English]` + .. _get-started-install_bat-windows: 使用脚本安装 ESP-IDF 工具 @@ -15,27 +17,26 @@ install.ps1 -该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。 +该命令可下载并安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。 该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。 .. _get-started-export_bat-windows: -使用“导出脚本”将 ESP-IDF 工具添加至 PATH +使用“导出脚本”将 ESP-IDF 工具添加至 PATH 环境变量 ================================================================================= -ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。 +ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符”创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。 -有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。 +有些情况下，您正在使用的命令提示符窗口并不是通过快捷方式打开的，此时如果想要在该窗口使用 ESP-IDF，您可以根据下方步骤将 ESP-IDF 工具添加至 PATH 环境变量。 -首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``:: +首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至安装 ESP-IDF 的目录，然后执行 ``export.bat``，具体命令如下:: - cd %userprofile%\esp\esp-idf - export.bat + cd %userprofile%\esp\esp-idf + export.bat -对于 Powershell 用户，请同样切换至 ESP-IDF 的安装路径，然后执行 ``export.ps1``:: +对于 Powershell 用户，请同样切换至安装 ESP-IDF 的目录，然后执行 ``export.ps1``，具体命令如下:: - cd ~/esp/esp-idf - export.ps1 - -运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。 + cd ~/esp/esp-idf + export.ps1 +运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。 \ No newline at end of file