mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
docs: provide CN translation for api-guides/tools/idf-docker-image.rst
This commit is contained in:
caixinying-git
parent
b0b722da33
commit
caf3f6b5fb
@ -1,23 +1,25 @@
|
||||
****************
|
||||
IDF Docker Image
|
||||
****************
|
||||
********************
|
||||
ESP-IDF Docker Image
|
||||
********************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
..
|
||||
When changing this page, please keep tools/docker/README.md in sync.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
IDF Docker image (``espressif/idf``) is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.
|
||||
ESP-IDF Docker image (``espressif/idf``) is intended for building applications and libraries with specific versions of ESP-IDF when doing automated builds.
|
||||
|
||||
The image contains:
|
||||
|
||||
- Common utilities such as git, wget, curl, zip.
|
||||
- Common utilities such as ``git``, ``wget``, ``curl``, and ``zip``.
|
||||
- Python 3.7 or newer.
|
||||
- A copy of a specific version of ESP-IDF (see below for information about versions). ``IDF_PATH`` environment variable is set, and points to ESP-IDF location in the container.
|
||||
- All the build tools required for the specific version of ESP-IDF: CMake, ninja, cross-compiler toolchains, etc.
|
||||
- A copy of a specific version of ESP-IDF. See below for information about versions. ``IDF_PATH`` environment variable is set and points to the ESP-IDF location in the container.
|
||||
- All the build tools required for the specific version of ESP-IDF: CMake, Ninja, cross-compiler toolchains, etc.
|
||||
- All Python packages required by ESP-IDF are installed in a virtual environment.
|
||||
|
||||
The image entrypoint sets up ``PATH`` environment variable to point to the correct version of tools, and activates the Python virtual environment. As a result, the environment is ready to use the ESP-IDF build system.
|
||||
The image ``ENTRYPOINT`` sets up the ``PATH`` environment variable to point to the correct version of tools, and activates the Python virtual environment. As a result, the environment is ready to use the ESP-IDF build system.
|
||||
|
||||
The image can also be used as a base for custom images, if additional utilities are required.
|
||||
|
||||
@ -42,87 +44,104 @@ Setting up Docker
|
||||
|
||||
Before using the ``espressif/idf`` Docker image locally, make sure you have Docker installed. Follow the instructions at https://docs.docker.com/install/, if it is not installed yet.
|
||||
|
||||
If using the image in CI environment, consult the documentation of your CI service on how to specify the image used for the build process.
|
||||
If using the image in a CI environment, consult the documentation of your CI service on how to specify the image used for the build process.
|
||||
|
||||
Building a project with CMake
|
||||
Building a Project with CMake
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In the project directory, run::
|
||||
In the project directory, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build
|
||||
|
||||
|
||||
The above command explained:
|
||||
|
||||
- ``docker run``: runs a Docker image. It is a shorter form of the command ``docker container run``.
|
||||
- ``--rm``: removes the container when the build is finished
|
||||
- ``-v $PWD:/project``: mounts the current directory on the host (``$PWD``) as ``/project`` directory in the container
|
||||
- ``espressif/idf``: uses Docker image ``espressif/idf`` with tag ``latest`` (implicitly added by Docker when no tag is specified)
|
||||
- ``idf.py build``: runs this command inside the container
|
||||
- ``--rm``: removes the container when the build is finished.
|
||||
- ``-v $PWD:/project``: mounts the current directory on the host (``$PWD``) as ``/project`` directory in the container.
|
||||
- ``espressif/idf``: uses Docker image ``espressif/idf`` with tag ``latest``. The ``latest`` tag is implicitly added by Docker when no tag is specified.
|
||||
- ``idf.py build``: runs this command inside the container.
|
||||
|
||||
To build with a specific Docker image tag, specify it as ``espressif/idf:TAG``, for example::
|
||||
To build with a specific Docker image tag, specify it as ``espressif/idf:TAG``, for example:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build
|
||||
|
||||
You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
|
||||
|
||||
Using the image interactively
|
||||
Using the Image Interactively
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It is also possible to do builds interactively, to debug build issues or test the automated build scripts. Start the container with `-i -t` flags::
|
||||
It is also possible to do builds interactively, to debug build issues or test the automated build scripts. Start the container with ``-i -t`` flags:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project -it espressif/idf
|
||||
|
||||
Then inside the container, use ``idf.py`` as usual:
|
||||
|
||||
Then inside the container, use ``idf.py`` as usual::
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py menuconfig
|
||||
idf.py build
|
||||
|
||||
.. note::
|
||||
|
||||
Commands which communicate with the development board, such as ``idf.py flash`` and ``idf.py monitor`` will not work in the container unless the serial port is passed through into the container. This can be done with Docker for Linux with the `device option`_. However currently this is not possible with Docker for Windows (https://github.com/docker/for-win/issues/1018) and Docker for Mac (https://github.com/docker/for-mac/issues/900). This limitation may be overcome by using `remote serial ports`_. An example how to do this can be found in the following `using remote serial port`_ section.
|
||||
Commands which communicate with the development board, such as ``idf.py flash`` and ``idf.py monitor`` does not work in the container, unless the serial port is passed through into the container. This can be done with Docker for Linux with the `device option`_. However, currently, this is not possible with Docker for Windows (https://github.com/docker/for-win/issues/1018) and Docker for Mac (https://github.com/docker/for-mac/issues/900). This limitation may be overcome by using `remote serial ports`_. An example of how to do this can be found in the following `using remote serial port`_ section.
|
||||
|
||||
|
||||
.. _using remote serial port:
|
||||
|
||||
Using remote serial port
|
||||
Using Remote Serial Port
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The `RFC2217`_ (Telnet) protocol can be used to remotely connect to a serial port. For more information please see the `remote serial ports`_ documentation in the esptool project. This method can also be used to access the serial port inside a Docker container if it cannot be accessed directly. Following is an example how to use the flash command from within a Docker container.
|
||||
|
||||
The `RFC2217`_ (Telnet) protocol can be used to remotely connect to a serial port. For more information please see the `remote serial ports`_ documentation in the ESP tool project. This method can also be used to access the serial port inside a Docker container if it cannot be accessed directly. Following is an example of how to use the Flash command from within a Docker container.
|
||||
|
||||
On host install and start ``esp_rfc2217_server``:
|
||||
|
||||
* On Windows, package is available as a one-file bundled executable created by pyinstaller and it can be downloaded from the `esptool releases`_ page in a zip archive along with other esptool utilities::
|
||||
* On Windows, the package is available as a one-file bundled executable created by ``pyinstaller`` and it can be downloaded from the `esptool releases`_ page in a ZIP archive along with other ESP tool utilities:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
esp_rfc2217_server -v -p 4000 COM3
|
||||
|
||||
* On Linux/MacOS, package is available as part of `esptool` which can be found in ESP-IDF environment or by installing using pip::
|
||||
* On Linux or macOS, the package is available as part of ``esptool``, which can be found in the ESP-IDF environment or by installing using ``pip``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install esptool
|
||||
|
||||
And then starting the server by executing::
|
||||
And then starting the server by executing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0
|
||||
|
||||
Now the device attached to the host can be flashed from inside a Docker container by using::
|
||||
Now the device attached to the host can be flashed from inside a Docker container by using:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v <host_path>:/<container_path> -w /<container_path> espressif/idf idf.py --port rfc2217://host.docker.internal:4000?ign_set_control flash
|
||||
|
||||
Please make sure that ``<host_path>`` is properly set to your project path on the host and ``<container_path>`` is set as a working directory inside the container with the ``-w`` option. The ``host.docker.internal`` is a special Docker DNS name to access the host. This can be replaced with host IP if necessary.
|
||||
Please make sure that ``<host_path>`` is properly set to your project path on the host, and ``<container_path>`` is set as a working directory inside the container with the ``-w`` option. The ``host.docker.internal`` is a special Docker DNS name to access the host. This can be replaced with a host IP if necessary.
|
||||
|
||||
|
||||
Building custom images
|
||||
Building Custom Images
|
||||
======================
|
||||
|
||||
The Dockerfile in ESP-IDF repository provides several build arguments which can be used to customize the Docker image:
|
||||
The Docker file in ESP-IDF repository provides several build arguments which can be used to customize the Docker image:
|
||||
|
||||
- ``IDF_CLONE_URL``: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. Default is ``https://github.com/espressif/esp-idf.git``.
|
||||
- ``IDF_CLONE_BRANCH_OR_TAG``: Name of a git branch or tag use when cloning ESP-IDF. This value is passed to ``git clone`` command using the ``--branch`` argument. Default is ``master``.
|
||||
- ``IDF_CHECKOUT_REF``: If this argument is set to a non-empty value, ``git checkout $IDF_CHECKOUT_REF`` command will be performed after cloning. This argument can be set to the SHA of the specific commit to check out, for example if some specific commit on a release branch is desired.
|
||||
- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments will be used when performing ``git clone``. This significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first.
|
||||
- ``IDF_INSTALL_TARGETS``: Comma-separated list of IDF targets to install toolchains for, or ``all`` to install toolchains for all targets. Selecting specific targets reduces the amount of data downloaded and the size of the resulting Docker image. Default is ``all``.
|
||||
- ``IDF_CLONE_URL``: URL of the repository to clone ESP-IDF from. Can be set to a custom URL when working with a fork of ESP-IDF. The default is ``https://github.com/espressif/esp-idf.git``.
|
||||
- ``IDF_CLONE_BRANCH_OR_TAG``: Name of a git branch or tag used when cloning ESP-IDF. This value is passed to the ``git clone`` command using the ``--branch`` argument. The default is ``master``.
|
||||
- ``IDF_CHECKOUT_REF``: If this argument is set to a non-empty value, ``git checkout $IDF_CHECKOUT_REF`` command performs after cloning. This argument can be set to the SHA of the specific commit to check out, for example, if some specific commit on a release branch is desired.
|
||||
- ``IDF_CLONE_SHALLOW``: If this argument is set to a non-empty value, ``--depth=1 --shallow-submodules`` arguments are be used when performing ``git clone``. This significantly reduces the amount of data downloaded and the size of the resulting Docker image. However, if switching to a different branch in such a "shallow" repository is necessary, an additional ``git fetch origin <branch>`` command must be executed first.
|
||||
- ``IDF_INSTALL_TARGETS``: Comma-separated list of ESP-IDF targets to install toolchains for, or ``all`` to install toolchains for all targets. Selecting specific targets reduces the amount of data downloaded and the size of the resulting Docker image. The default is ``all``.
|
||||
|
||||
To use these arguments, pass them via the ``--build-arg`` command line option. For example, the following command will build a Docker image with a shallow clone of ESP-IDF v4.4.1 and tools for ESP32-C3, only::
|
||||
To use these arguments, pass them via the ``--build-arg`` command line option. For example, the following command builds a Docker image with a shallow clone of ESP-IDF v4.4.1 and tools for ESP32-C3 only：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build -t idf-custom:v4.4.1-esp32c3 \
|
||||
--build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \
|
||||
|
||||
@ -1 +1,155 @@
|
||||
.. include:: ../../../en/api-guides/tools/idf-docker-image.rst
|
||||
********************
|
||||
ESP-IDF Docker 镜像
|
||||
********************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
..
|
||||
When changing this page, please keep tools/docker/README.md in sync.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
ESP-IDF Docker 镜像 (``espressif/idf``) 为使用特定版本的 ESP-IDF 自动化构建应用程序和库而设计。
|
||||
|
||||
该镜像包含以下内容：
|
||||
|
||||
- 常见的实用工具，如 ``git``、``wget``、``curl`` 和 ``zip``。
|
||||
- Python 3.7 或更高版本。
|
||||
- 特定版本 ESP-IDF 的副本。有关版本信息，请参阅下文。该副本中设置了 ``IDF_PATH`` 环境变量，并指向容器中 ESP-IDF 的位置。
|
||||
- 构建特定版本 ESP-IDF 所需工具：CMake、Ninja、交叉编译器工具链等。
|
||||
- ESP-IDF 需要的所有 Python 软件包。这些软件包均已安装在虚拟环境中。
|
||||
|
||||
镜像 ``ENTRYPOINT`` 会设置 ``PATH`` 环境变量，指向正确版本的工具，并激活 Python 虚拟环境。此时，环境已经准备好，可以使用 ESP-IDF 构建系统。
|
||||
|
||||
如需使用其他工具，可用该镜像作为基础自定义镜像。
|
||||
|
||||
标签
|
||||
====
|
||||
|
||||
该镜像维护了以下多个标签：
|
||||
|
||||
- ``latest``：跟踪 ESP-IDF 的 ``master`` 分支
|
||||
- ``vX.Y``：对应 ESP-IDF 的版本 ``vX.Y``
|
||||
- ``release-vX.Y``：跟踪 ESP-IDF 的 ``release/vX.Y`` 分支
|
||||
|
||||
.. note::
|
||||
|
||||
在引入镜像功能前发布的 ESP-IDF 版本没有对应的 Docker 镜像版本。要查找最新可用标签列表，请参阅 https://hub.docker.com/r/espressif/idf/tags。
|
||||
|
||||
使用 Docker
|
||||
===========
|
||||
|
||||
设置 Docker
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
在本地使用 ``espressif/idf`` Docker 镜像前，请确保已安装 Docker。如果本地未安装 Docker，请按 https://docs.docker.com/install/ 提供的说明完成安装。
|
||||
|
||||
如果在 CI 环境中使用该镜像，请参阅 CI 服务说明文档，了解如何指定用于构建的镜像。
|
||||
|
||||
使用 CMake 构建项目
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
在项目目录下，运行以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build
|
||||
|
||||
该命令具体内容如下：
|
||||
|
||||
- ``docker run``：运行 Docker 镜像。此为 ``docker container run`` 命令的缩写形式。
|
||||
- ``--rm``：构建完成后删除相应容器。
|
||||
- ``-v $PWD:/project``：将主机当前目录 (``$PWD``) 挂载为容器中的 ``/project`` 目录。
|
||||
- ``espressif/idf``：使用标签为 ``latest`` 的 Docker 镜像 ``espressif/idf``。未指定标签时，Docker 会隐式添加 ``latest`` 标签。
|
||||
- ``idf.py build``：在容器内运行此命令。
|
||||
|
||||
要以特定 Docker 镜像标签进行构建，请将其指定为 ``espressif/idf:TAG``，示例如下：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build
|
||||
|
||||
要查看最新可用标签列表，请参阅 https://hub.docker.com/r/espressif/idf/tags。
|
||||
|
||||
交互使用镜像
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Docker 也支持以交互方式进行构建，以调试构建问题或测试自动构建脚本。请使用 ``-i -t`` 标志启动容器，示例如下：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v $PWD:/project -w /project -it espressif/idf
|
||||
|
||||
接着在容器内部照常使用 ``idf.py``：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
idf.py menuconfig
|
||||
idf.py build
|
||||
|
||||
.. note::
|
||||
|
||||
若未将串行接口传递到容器中，则 ``idf.py flash`` 和 ``idf.py monitor`` 等与开发板通信的命令在容器中无法正常工作。对于 Linux 系统，可以使用 `设备选项`_ 将串行接口传递到容器中。然而，目前 Windows 系统 (https://github.com/docker/for-win/issues/1018) 和 Mac 系统 (https://github.com/docker/for-mac/issues/900) 中 Docker 不支持此功能。可以使用 `远程串行接口`_ 克服此限制。有关如何执行此操作，请参阅以下 `使用远程串行接口`_ 章节。
|
||||
|
||||
|
||||
.. _using remote serial port:
|
||||
|
||||
使用远程串行接口
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`RFC2217`_ (Telnet) 协议可用于远程连接到串行接口，详情请参阅 ESP 工具项目的 `远程串行接口`_ 文档。如果无法直接访问 Docker 容器内的串行接口，也可使用该协议进行访问。以下示例展示了如何从 Docker 容器内部使用烧写命令。
|
||||
|
||||
在主机上安装并启动 ``esp_rfc2217_server``：
|
||||
|
||||
* 在 Windows 系统中，该软件包以一个文件的形式提供，这个文件是由 ``pyinstaller`` 创建的可执行文件，可以从 `ESP 工具版本`_ 页面以 ZIP 压缩文件的形式与其他 ESP 工具一起下载：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
esp_rfc2217_server -v -p 4000 COM3
|
||||
|
||||
* 在 Linux 或 macOS 系统中，该软件包是 ``esptool`` 的组成部分，可以在 ESP-IDF 环境中找到，或使用以下 ``pip`` 命令安装：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pip install esptool
|
||||
|
||||
随后执行以下命令启动服务器：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0
|
||||
|
||||
此时，便可使用以下命令，从 Docker 容器内部烧写连接到主机的设备：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker run --rm -v <host_path>:/<container_path> -w /<container_path> espressif/idf idf.py --port rfc2217://host.docker.internal:4000?ign_set_control flash
|
||||
|
||||
请确保将 ``<host_path>`` 正确设置为主机上的项目路径，并使用 ``-w`` 选项将 ``<container_path>`` 设置为容器内的工作目录。``host.docker.internal`` 为特殊的 Docker DNS 名称，用于访问主机。如有需要，可以将其替换为主机的 IP 地址。
|
||||
|
||||
|
||||
构建自定义镜像
|
||||
======================
|
||||
|
||||
ESP-IDF 库中的 Docker 文件提供了以下构建参数，可用于构建自定义 Docker 镜像：
|
||||
|
||||
- ``IDF_CLONE_URL``：克隆 ESP-IDF 存储库的 URL。在使用 ESP-IDF 分支时，可以将该参数设置为自定义 URL，默认值为 ``https://github.com/espressif/esp-idf.git``。
|
||||
- ``IDF_CLONE_BRANCH_OR_TAG``：克隆 ESP-IDF 时使用的 git 分支或标签的名称。该参数将作为 ``git clone`` 命令的 ``--branch`` 参数传递，默认值为 ``master``。
|
||||
- ``IDF_CHECKOUT_REF``：如果将此参数设置为非空值，在克隆之后会执行 ``git checkout $IDF_CHECKOUT_REF`` 命令。可以将此参数设置为特定 commit 的 SHA 值，以便切换到所需的版本分支或 commit。例如，在希望使用特定版本分支上的某个 commit 时，就可以将此参数设置为该 commit 的 SHA 值。
|
||||
- ``IDF_CLONE_SHALLOW``：如果将此参数设置为非空值，则会在执行 ``git clone`` 时使用 ``--depth=1 --shallow-submodules`` 参数。这可以极大减少下载的数据量及生成的 Docker 镜像大小。然而，如果需要切换到此类“浅层”存储库中的其他分支，必须先执行额外的 ``git fetch origin <branch>`` 命令。
|
||||
- ``IDF_INSTALL_TARGETS``：以逗号分隔的 ESP-IDF 目标列表，用于安装工具链，或者使用 ``all`` 安装所有目标的工具链。选择特定目标可以减少下载的数据量和生成的 Docker 镜像的大小。该参数默认值为 ``all``。
|
||||
|
||||
要使用以上参数，请通过 ``--build-arg`` 命令行选项传递。例如，以下命令使用 ESP-IDF v4.4.1 的浅克隆以及仅适用于 ESP32-C3 的工具链构建了 Docker 镜像：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
docker build -t idf-custom:v4.4.1-esp32c3 \
|
||||
--build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \
|
||||
--build-arg IDF_CLONE_SHALLOW=1 \
|
||||
--build-arg IDF_INSTALL_TARGETS=esp32c3 \
|
||||
tools/docker
|
||||
|
||||
.. _远程串行接口: https://docs.espressif.com/projects/esptool/en/latest/esptool/remote-serial-ports.html
|
||||
.. _RFC2217: http://www.ietf.org/rfc/rfc2217.txt
|
||||
.. _ESP 工具版本: https://github.com/espressif/esptool/releases
|
||||
.. _设备选项: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities
|
||||
|
||||
Loading…
Reference in New Issue
Block a user