From c7d511277163726434e08725b250cddb38c5c660 Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Tue, 1 Aug 2023 11:18:25 +1000 Subject: [PATCH 1/2] idf-docker-image.rst: Run with current user ID instead of root. Rather than running the command inside the container as root, which will mean that any build artifacts created will be owned by root on the host, run the command as the current user. This requires setting a temporary home directory as idf.py will try to access e.g. ~/.cache, so just use /tmp inside the container which is ephemeral anyway. This also allows the command to use `git`. without setting the user ID, `docker run ... git status` will fail with fatal: detected dubious ownership in repository at '/project' Also added the missing explanation for `-w /project`. Signed-off-by: Jim Mussared --- docs/en/api-guides/tools/idf-docker-image.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/en/api-guides/tools/idf-docker-image.rst b/docs/en/api-guides/tools/idf-docker-image.rst index 1b7cf9b6ba..356b6b7aa5 100644 --- a/docs/en/api-guides/tools/idf-docker-image.rst +++ b/docs/en/api-guides/tools/idf-docker-image.rst @@ -53,13 +53,16 @@ In the project directory, run: .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp 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. +- ``-w /project``: makes ``/project`` the working directory for the command. +- ``-u $UID``: makes the command run with your user ID so that files are created as you (instead of root). +- ``-e HOME=/tmp``: gives the user a home directory for storing temporary files created ``by idf.py`` in ``~/.cache``. - ``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. @@ -67,7 +70,7 @@ To build with a specific Docker image tag, specify it as ``espressif/idf:TAG``, .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp 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. @@ -78,7 +81,7 @@ It is also possible to do builds interactively, to debug build issues or test th .. code-block:: bash - docker run --rm -v $PWD:/project -w /project -it espressif/idf + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp -it espressif/idf Then inside the container, use ``idf.py`` as usual: From 1c2a8a89178300471f3c73b024d1c234d635f4be Mon Sep 17 00:00:00 2001 From: daiziyan Date: Tue, 15 Aug 2023 11:11:13 +0800 Subject: [PATCH 2/2] docs: provide CN trans for idf-docker-image --- docs/en/api-guides/tools/idf-docker-image.rst | 2 +- docs/zh_CN/api-guides/tools/idf-docker-image.rst | 9 ++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/en/api-guides/tools/idf-docker-image.rst b/docs/en/api-guides/tools/idf-docker-image.rst index 356b6b7aa5..dddc6f87d5 100644 --- a/docs/en/api-guides/tools/idf-docker-image.rst +++ b/docs/en/api-guides/tools/idf-docker-image.rst @@ -62,7 +62,7 @@ The above command explained: - ``-v $PWD:/project``: mounts the current directory on the host (``$PWD``) as ``/project`` directory in the container. - ``-w /project``: makes ``/project`` the working directory for the command. - ``-u $UID``: makes the command run with your user ID so that files are created as you (instead of root). -- ``-e HOME=/tmp``: gives the user a home directory for storing temporary files created ``by idf.py`` in ``~/.cache``. +- ``-e HOME=/tmp``: gives the user a home directory for storing temporary files created by ``idf.py`` in ``~/.cache``. - ``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. diff --git a/docs/zh_CN/api-guides/tools/idf-docker-image.rst b/docs/zh_CN/api-guides/tools/idf-docker-image.rst index 275f216645..fda252b5de 100644 --- a/docs/zh_CN/api-guides/tools/idf-docker-image.rst +++ b/docs/zh_CN/api-guides/tools/idf-docker-image.rst @@ -53,13 +53,16 @@ ESP-IDF Docker 镜像 (``espressif/idf``) 为使用特定版本的 ESP-IDF 自 .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp espressif/idf idf.py build 该命令具体内容如下： - ``docker run``：运行 Docker 镜像。此为 ``docker container run`` 命令的缩写形式。 - ``--rm``：构建完成后删除相应容器。 - ``-v $PWD:/project``：将主机当前目录 (``$PWD``) 挂载为容器中的 ``/project`` 目录。 +- ``-w /project``：使 ``/project`` 成为当前命令的工作目录。 +- ``-u $UID``：以当前用户的 ID 运行命令，使文件以当前用户而非 root 用户的身份创建。 +- ``-e HOME=/tmp``：为用户提供一个主目录，用于将 ``idf.py`` 创建的临时文件保存在 ``~/.cache`` 中。 - ``espressif/idf``：使用标签为 ``latest`` 的 Docker 镜像 ``espressif/idf``。未指定标签时，Docker 会隐式添加 ``latest`` 标签。 - ``idf.py build``：在容器内运行此命令。 @@ -67,7 +70,7 @@ ESP-IDF Docker 镜像 (``espressif/idf``) 为使用特定版本的 ESP-IDF 自 .. code-block:: bash - docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp espressif/idf:release-v4.4 idf.py build 要查看最新可用标签列表，请参阅 https://hub.docker.com/r/espressif/idf/tags。 @@ -78,7 +81,7 @@ Docker 也支持以交互方式进行构建，以调试构建问题或测试自 .. code-block:: bash - docker run --rm -v $PWD:/project -w /project -it espressif/idf + docker run --rm -v $PWD:/project -w /project -u $UID -e HOME=/tmp -it espressif/idf 接着在容器内部照常使用 ``idf.py``：