Skip to content

Commit

Permalink
Merge branch 'docs/add_Chinese_translation_for_api-guides/tools/idf-d…
Browse files Browse the repository at this point in the history
…ocker-image.rst' into 'master'

docs: provide CN translation for api-guides/tools/idf-docker-image.rst

Closes DOC-5399

See merge request espressif/esp-idf!24080
  • Loading branch information
caixinying-git committed Jul 5, 2023
2 parents a7e5d49 + caf3f6b commit 907e92b
Show file tree
Hide file tree
Showing 2 changed files with 213 additions and 40 deletions.
97 changes: 58 additions & 39 deletions docs/en/api-guides/tools/idf-docker-image.rst
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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:

docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build
.. 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:

esp_rfc2217_server -v -p 4000 COM3
.. code-block:: bash
* On Linux/MacOS, package is available as part of `esptool` which can be found in ESP-IDF environment or by installing using pip::
esp_rfc2217_server -v -p 4000 COM3
pip install esptool
* 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``:

And then starting the server by executing::
.. code-block:: bash
esp_rfc2217_server.py -v -p 4000 /dev/ttyUSB0
pip install esptool
Now the device attached to the host can be flashed from inside a Docker container by using::
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:

.. 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. 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``.

- ``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``.
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:

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::
.. code-block:: bash
docker build -t idf-custom:v4.4.1-esp32c3 \
--build-arg IDF_CLONE_BRANCH_OR_TAG=v4.4.1 \
Expand Down
Loading

0 comments on commit 907e92b

Please sign in to comment.