From 2188e3fdca0afd185b8feb9d34c6490dfdec5323 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Thu, 26 May 2022 01:04:14 +0200 Subject: [PATCH] docs: document build arguments of the Docker image --- docs/en/api-guides/tools/idf-docker-image.rst | 24 +++++++++++++++---- 1 file changed, 20 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 2fdaa779e8..a64aa68c05 100644 --- a/docs/en/api-guides/tools/idf-docker-image.rst +++ b/docs/en/api-guides/tools/idf-docker-image.rst @@ -59,11 +59,9 @@ The above command explained: To build with a specific docker image tag, specify it as ``espressif/idf:TAG``:: - docker run --rm -v $PWD:/project -w /project espressif/idf:v4.0 idf.py build + docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.4 idf.py build -.. note:: - - At the time of writing, v4.0 release of ESP-IDF does not exist, yet, so the above command will not work. You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags. +You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags. Building a project with GNU Make @@ -94,3 +92,21 @@ Then inside the container, use ``idf.py`` as usual:: .. 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. 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). + +Building custom images +====================== + +The Dockerfile 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 `` command must be executed first. + +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:: + + 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