Doc/update CN translation for files on setting up toolchain from scratch in get started

This commit is contained in:
Dai Zi Yan 2020-11-30 17:58:27 +08:00 committed by Krzysztof Budzynski
parent 079247b42a
commit c7bebb0413
7 changed files with 87 additions and 66 deletions

View File

@ -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<macos-setup>`, 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<macos-setup>`, 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 <get-started-customized-setup>` 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

View File

@ -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 <ninja-dl_>`_).
Download the Ninja_ latest stable Windows release from the (`download page <ninja-dl_>`_).
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).
@ -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/

View File

@ -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

View File

@ -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:`标准设置指南 <setup-linux-toolchain-add-it-to-path-legacy>` 的介绍,将工具链添加到 ``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` 章节继续设置开发环境。

View File

@ -7,11 +7,11 @@
软件包管理器
===============
从零开始设置工具链,您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者,您也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
从零开始设置工具链,您需要安装 MacPorts_ 或 Homebrew_ 软件包管理器。或者,您也可以直接下载 :doc:`预编译的工具链 <macos-setup>`。
MacPorts 需要完整的 XCode 软件,而 homebrew 只需要安装 XCode 命令行工具即可。
MacPorts 需要完整的 XCode 软件,而 Homebrew 只需要安装 XCode 命令行工具即可。
.. _homebrew: https://brew.sh/
.. _Homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节,查看可能需要从头开始设置工具链的情况。
@ -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` 章节继续设置开发环境

View File

@ -4,7 +4,7 @@
:link_to_translation:`en:[English]`
除了使用 :doc:`ESP-IDF 工具安装器 <windows-setup>`,用户也可以手动设置 Windows 环境下的工具链,这是本文的主要内容。手动安装工具可以更好地控制安装流程,同时也方便高阶用户进行自定义安装。
除了使用 :doc:`ESP-IDF 工具安装器 <windows-setup>`,用户也可以手动设置 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`` 。但是目前暂无关于此工具的说明文档。
从(`下载页面 <ninja-dl_>`_)下载最新发布的 Windows 平台稳定版 ninja_。
请从 `下载页面 <ninja-dl_>`_ 下载最新发布的 Windows 平台稳定版 Ninja_。
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件,包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录,并 :ref:`添加到您的路径 <add-directory-windows-path>` (或者选择您路径中的已有目录)。
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件,包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录,并 :ref:`添加到 Path 环境变量 <add-directory-windows-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:`添加到您的路径 <add-directory-windows-path>`
工具链设置
===============
@ -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:`添加到您的路径 <add-directory-windows-path>`。例如,``C:\Program Files\xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf\bin``
然后,请将该目录下的 ``bin`` 子目录 :ref:`添加到 Path 环境变量 <add-directory-windows-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`` 变量(选择“用户”或“系统路径”,具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``
双击 ``Path`` 变量(选择“用户路径”或“系统路径”,具体取决于您是否希望其他用户的 Path 中也存在该目录)。最后在值的末尾增加 ``;<new value>``
后续步骤
==========
继续设置开发环境,请前往 :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

View File

@ -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 工具了。